back
loading skill details...
Control Telegram Media Server downloads over REST: add URLs/torrents, list status, delete, and search via Prowlarr.
---
name: tms
version: "1.0.9"
description: "Control Telegram Media Server downloads over REST: add URLs/torrents, list status, delete, and search via Prowlarr."
homepage: https://github.com/NikitaDmitryuk/telegram-media-server/tree/main/openclaw-skill-tms
user-invocable: false
metadata: {"openclaw":{"requires":{"env":[]},"primaryEnv":"TMS_API_KEY"}}
---
# TMS (Telegram Media Server) API skill
Use this skill when the user wants to add downloads, check download status, remove a download, or search for torrents via the TMS backend. All requests go to the TMS REST API.
**How to use:** This skill is not a `/tms` slash command. The agent must make HTTP requests (GET/POST/DELETE) to the TMS endpoints. Prefer OpenClaw's HTTP/web request capability when available; do not use shell commands or `curl` unless HTTP tooling is unavailable. The **full API contract** (paths, request/response schemas, examples) is included in this document below, so there is no need to fetch any URL to get the API spec.
## 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:** If env `TMS_API_KEY` is configured, always send every API request with `Authorization: Bearer <TMS_API_KEY>` or header `X-API-Key: <TMS_API_KEY>`. If a request returns 401, retry once with the configured `TMS_API_KEY`; do not ask the user to reveal the key. Only omit auth when `TMS_API_KEY` is truly absent and TMS is explicitly configured to allow unauthenticated localhost requests.
## 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 queued, active, and completed/library items with `id`, `title`, `status` (queued, downloading, converting, completed, failed, stopped), `progress`, `conversion_progress`, `error` (if failed), `position_in_queue` (if queued). Empty state is `[]`. 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. If the user asks to add a movie and does not explicitly request a duplicate, call `GET /downloads` first and avoid adding an existing item with the same title/status.
4. **Delete download** — `DELETE {BaseURL}/api/v1/downloads/{id}` — removes the item everywhere: active download or queue, DB/library row, local files, and qBittorrent entry when applicable. 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.
```yaml
openapi: 3.1.0
info:
title: TMS REST API
description: |
Telegram Media Server API. Use to add downloads by URL (video/magnet/torrent), list queued/active/completed
downloads with status, remove downloads everywhere, 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/library). Returns an 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). Empty state is []. 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. If the user did not explicitly request a duplicate, call GET /downloads first and avoid adding an existing title. 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: Remove a download everywhere
description: Call to remove the item with given id everywhere: active download or queue, DB/library row, local files, and qBittorrent entry when applicable. id is the numeric id returned by POST /downloads or GET /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 removed
'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.
don't have the plugin yet? install it then click "run inline in claude" again.