tms

name	tms
version	1.0.6
description	Manage downloads via Telegram Media Server (TMS) REST API — add by URL (video/magnet/torrent), list, delete, search torrents.
metadata	{"openclaw":{"requires":{"env":"[Truncated]"},"primaryEnv":"TMS_API_URL"}}

TMS (Telegram Media Server) API skill

Use this skill when the user wants to add downloads, check download status, stop a download, or search for torrents via the TMS backend. All requests go to the TMS REST API.

How to use: This skill does not add a "tms" command. The agent must make HTTP requests (GET/POST/DELETE) to the TMS endpoints. The full API contract (paths, request/response schemas, examples) is included in this document below — no need to fetch any URL to get the API spec. Use the OpenAPI spec (inline) section to build and invoke API calls.

Base URL and authentication

• Base URL: Use env TMS_API_URL if set; otherwise, when TMS and OpenClaw run on the same host, use http://127.0.0.1:8080 (TMS default API listen). Do not add a trailing slash. All endpoint paths in the spec use the prefix /api/v1 — e.g. GET /health means GET {BaseURL}/api/v1/health.
• Authentication: Optional. When TMS and OpenClaw run on the same host, TMS accepts requests from localhost without a key — TMS_API_KEY can be omitted. When OpenClaw runs on another host (or you want auth), set TMS_API_KEY and send every API request with either Authorization: Bearer <TMS_API_KEY> or header X-API-Key: <TMS_API_KEY>.

Operations (summary)

1. Health check — GET {BaseURL}/api/v1/health — returns {"status":"ok"} if the API is up.
2. List downloads — GET {BaseURL}/api/v1/downloads — returns a JSON array of downloads with id, title, status (queued, downloading, converting, completed, failed, stopped), progress, conversion_progress, error (if failed), position_in_queue (if queued). Snapshot is best-effort.
3. Add download — POST {BaseURL}/api/v1/downloads with JSON body {"url": "<url>", "title": "<optional>"}. URL can be: video URL (yt-dlp), magnet link (magnet:...), .torrent file URL, or (when Prowlarr is configured on TMS) Prowlarr proxy download URL. Prefer magnet from search results when adding a torrent. Optional title overrides the display name. Response: 201 with {"id": <number>, "title": "<string>"}. Use id for delete or status.
4. Delete download — DELETE {BaseURL}/api/v1/downloads/{id} — stops and removes the download. Response: 204 no body. id is the numeric id from the add response or list.
5. Search torrents — GET {BaseURL}/api/v1/search?q=<query>&limit=20&quality=1080 — requires Prowlarr configured on TMS. q is required; limit (1–100, default 20) and quality (optional filter) may be used. Returns array of {title, size, magnet, torrent_url, indexer_name, peers}. When adding from search, use the magnet field in POST /downloads (or torrent_url); you may pass title from the result.

Detailed request/response schemas and status codes are in the OpenAPI spec (inline) below.

OpenAPI spec (inline)

The following YAML is the full TMS API contract. Paths are relative to base path /api/v1; full URL = {BaseURL} + path (e.g. {BaseURL}/api/v1/health). Inline spec is copied from internal/api/openapi/openapi-llm.yaml; keep in sync when API changes.

openapi: 3.1.0
info:
  title: TMS REST API
  description: |
    Telegram Media Server API. Use to add downloads by URL (video/magnet/torrent), list downloads with status,
    delete a download, or search torrents. All endpoints require Authorization Bearer or X-API-Key.
  version: 1.0.0

servers:
  - url: /api/v1
    description: Base path (prepend your TMS base URL, e.g. from TMS_API_URL)

tags:
  - name: health
  - name: downloads
  - name: search

security:
  - BearerAuth: []
  - ApiKeyHeader: []

paths:
  /health:
    get:
      tags: [health]
      summary: Check API availability
      description: Call to         {}               
       
      
        
           
          
            
               {   }

  
    
       []
        
              
      
        
              
          
            
              
                 
                 {   }
    
       []
         
              
      
         
        
          
             {   }
             {   }
      
        
            
          
            
               {   }
        
               
          
            
               {   }
        
           
          
            
               {   }
        
            
          
            
               {   }

  
    
       []
           
                                 
       
      
          
           
           
           {  ,   }
      
        
            
        
               
          
            
               {   }
        
           
          
            
               {   }
        
            
          
            
               {   }

  
    
       []
        
              
      
          
           
           
           {   }
          
           
           {  ,  ,  ,   }
          
           
           {   }
      
        
              
          
            
              
                 
                 {   }
        
            
          
            
               {   }
        
           
          
            
               {   }
        
                
          
            
               {   }


  
    
       
       
        
    
       
       
       

  
    
       
       []
      
         {  ,   }

    
       
      
         {   }
         {   }
         {  ,  [, , , , , ] }
         {  ,  ,   }
         {  ,  ,   }
         {   }
         {   }

    
       
       []
      
         {   }
         {  ,         }

    
       
      
         {   }
         {   }

    
       
      
         {   }
         {   }
         {   }
         {   }
         {   }
         {   }

    
       
       []
      
         {   }

Webhook (optional)

If TMS is configured with TMS_WEBHOOK_URL pointing to an endpoint OpenClaw can receive, TMS will POST to that URL when a download completes, fails, or is stopped. Body: id, title, status (completed|failed|stopped), error (if failed), event_id (UUID). When TMS_WEBHOOK_TOKEN is set in TMS config, TMS sends Authorization: Bearer <TMS_WEBHOOK_TOKEN> (required for OpenClaw gateway hooks). Delivery is best-effort (no guaranteed delivery). Use this to notify the user in chat when a download finishes.