TMS (Telegram Media Server)

Manage downloads via Telegram Media Server (TMS) REST API — add by URL (video/magnet/torrent URL) or torrent_base64 (.torrent bytes), list, delete, search to...

Security Scan

This is an instruction-only skill that consistently documents and directs the agent to call a Telegram Media Server (TMS) REST API; its requirements and instructions align with the described purpose and it does not request unrelated credentials or install code.

Purpose & Capability

The name/description match the runtime instructions: the skill is an API client for TMS and contains an inline OpenAPI spec. It does not ask for unrelated binaries, secrets, or system paths. Declared primaryEnv (TMS_API_URL) and optional TMS_API_KEY are coherent with the stated purpose.

Instruction Scope

Instructions are focused on making HTTP calls to the TMS API (health, list, add, delete, search). Two points to note: (1) defaulting BaseURL to http://127.0.0.1:8080 means the agent will target localhost by default, which is expected for same-host integrations but also enables access to local services; (2) the doc says torrent_base64 can be sent when the agent has the .torrent file content (e.g. user upload or read from workspace), which implies the agent may read workspace-uploaded files — this is within scope but worth awareness.

Install Mechanism

Instruction-only skill with no install spec and no code to write or execute. Lowest-risk install posture (nothing is downloaded or written to disk by the skill itself).

Credentials

No required environment variables are listed; TMS_API_URL is the declared primaryEnv and TMS_API_KEY is optional in the docs. The requested envs are minimal and appropriate for an HTTP client to TMS; nothing unrelated is requested.

Persistence & Privilege

always:false and no special persistence is requested. The skill is allowed to be invoked autonomously by default (platform default); this is normal for skills and not in itself a concern.

Assessment

This skill is coherent and appears to only instruct the agent to talk to a TMS API. Before installing: (1) ensure the TMS instance you point to (TMS_API_URL) is one you control and trust; (2) when the agent is not colocated with TMS, set a dedicated TMS_API_KEY and store it per-skill (do not reuse broad keys); (3) be aware the default BaseURL uses localhost — the agent will be able to reach local services when enabled, so restrict the skill or disable autonomous invocation if you don't want the agent to start/stop downloads without explicit prompts; (4) if you accept torrent files via uploads, be careful what files are placed in the agent workspace (the skill supports sending torrent_base64 derived from workspace files); (5) secure any webhook endpoints and rotate keys if exposed. If you want extra caution, disable model autonomous invocation for this skill or require explicit user confirmation before performing add/delete operations.

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 that includes exactly one of url or torrent_base64, plus optional title.
   • url: video URL (yt-dlp), magnet (magnet:...), HTTPS URL to a .torrent file, or (when Prowlarr is on TMS) Prowlarr proxy download URL. Prefer magnet from search results when adding a torrent.
   • torrent_base64: standard Base64 encoding of a .torrent file’s raw bytes (no extra HTTP fetch by TMS). Use when the agent has the torrent file content (e.g. user upload, read from disk in workspace) but no public HTTPS URL. Body size limit applies (~1 MiB JSON). 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 URL) or torrent_base64 (.torrent file), 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 verify TMS API is reachable. Returns 200 and {"status":"ok"}. No auth required for this endpoint in some setups; if 401, send Bearer or X-API-Key.
      operationId: getHealth
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthResponse' }

  /downloads:
    get:
      tags: [downloads]
      summary: List downloads
      description: |
        Call to get current downloads (queued, active, completed). Returns array of items with id, title, status (queued|downloading|converting|completed|failed|stopped), progress (0-100), conversion_progress, error (if failed), position_in_queue (if queued). Snapshot is best-effort.
      operationId: listDownloads
      responses:
        '200':
          description: Array of download items
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/DownloadItem' }
    post:
      tags: [downloads]
      summary: Create a download
      description: |
        Call to add a download. Body: JSON with exactly one of "url" or "torrent_base64", plus optional "title". "url": video URL (yt-dlp), magnet (magnet:...), HTTPS URL to a .torrent file, or Prowlarr proxy download URL. "torrent_base64": standard Base64 of a .torrent file (no separate HTTP fetch). Prefer magnet from search results when applicable. Response gives id (number) and title (string). Use this id for DELETE /downloads/{id}.
      operationId: addDownload
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AddDownloadRequest' }
            example: { url: "magnet:?xt=urn:btih:abc123" }
      responses:
        '201':
          description: Download created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AddDownloadResponse' }
        '400':
          description: Missing url or invalid URL
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '500':
          description: Server error
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /downloads/{id}:
    delete:
      tags: [downloads]
      summary: Stop and remove a download
      description: Call to stop the download with given id and remove it. id is the numeric id returned by POST /downloads. Returns 204 with no body on success.
      operationId: deleteDownload
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer, minimum: 1 }
      responses:
        '204':
          description: Download stopped
        '400':
          description: Invalid id (not a number)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '500':
          description: Server error
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /search:
    get:
      tags: [search]
      summary: Search torrents
      description: |
        Call to search torrents (requires Prowlarr configured). Query param "q" (required): search string. "limit" (optional, 1-100, default 20): max results. "quality" (optional): filter by substring in release title (e.g. 1080). Returns array of objects with title, size, magnet, torrent_url, indexer_name, peers. When adding a download, prefer the magnet field in POST /downloads; you may also pass title from the result.
      operationId: searchTorrents
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: quality
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Array of search results
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SearchResultItem' }
        '400':
          description: Missing q
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: Search not configured or Prowlarr error
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    HealthResponse:
      type: object
      required: [status]
      properties:
        status: { type: string, example: "ok" }

    DownloadItem:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        status: { type: string, enum: [queued, downloading, converting, completed, failed, stopped] }
        progress: { type: integer, minimum: 0, maximum: 100 }
        conversion_progress: { type: integer, minimum: 0, maximum: 100 }
        error: { type: string }
        position_in_queue: { type: integer }

    AddDownloadRequest:
      type: object
      description: Exactly one of url or torrent_base64 must be present.
      properties:
        url: { type: string }
        torrent_base64: { type: string, description: Standard Base64-encoded .torrent file }
        title: { type: string, description: Optional display name e.g. from search result }

    AddDownloadResponse:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }

    SearchResultItem:
      type: object
      properties:
        title: { type: string }
        size: { type: integer }
        magnet: { type: string }
        torrent_url: { type: string }
        indexer_name: { type: string }
        peers: { type: integer }

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error: { type: string }

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.