torrentclaw-skill/references/api-reference.md

TorrentClaw API Reference

Search Response Schema

{
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "results": [
    {
      "id": 1,
      "imdbId": "tt1375666",
      "tmdbId": "27205",
      "contentType": "movie",
      "title": "Inception",
      "titleOriginal": "Inception",
      "year": 2010,
      "overview": "A thief who steals corporate secrets...",
      "posterUrl": "https://image.tmdb.org/t/p/w500/oYuLEt3zVCKq57qu2F8dT7NIa6f.jpg",
      "genres": ["Action", "Science Fiction", "Adventure"],
      "ratingImdb": "8.8",
      "ratingTmdb": "8.4",
      "contentUrl": "/movies/inception-2010-1",
      "hasTorrents": true,
      "maxSeeders": 847,
      "torrents": [
        {
          "infoHash": "aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
          "magnetUrl": "magnet:?xt=urn:btih:aaf1e71c...&dn=Inception+2010+1080p&tr=udp://tracker.opentrackr.org:1337/announce&tr=...",
          "torrentUrl": "/api/v1/torrent/aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
          "quality": "1080p",
          "codec": "x265",
          "sourceType": "BluRay",
          "sizeBytes": "2147483648",
          "seeders": 847,
          "leechers": 23,
          "source": "yts",
          "qualityScore": 85,
          "scrapedAt": "2026-02-13T10:30:00Z",
          "uploadedAt": "2024-03-15T12:00:00Z",
          "languages": ["en"],
          "audioCodec": "AAC",
          "hdrType": null,
          "releaseGroup": "YTS",
          "isProper": false,
          "isRepack": false,
          "isRemastered": false,
          "season": null,
          "episode": null
        }
      ]
    }
  ]
}

Allowed Genres

Action, Adventure, Animation, Comedy, Crime, Documentary, Drama, Family, Fantasy, History, Horror, Music, Mystery, Romance, Science Fiction, Thriller, War, Western, Reality, Talk, News, Soap, Kids, TV Movie, Action & Adventure, Sci-Fi & Fantasy, War & Politics

API Key Authentication

Request Headers:

Authorization: Bearer tc_live_xxxxx

Or via query parameter:

?api_key=tc_live_xxxxx

Response Headers:

X-RateLimit-Tier: free
X-RateLimit-Remaining: 115
X-Api-Key-Id: tc_live_abc1

Rate Limit Tiers:

• Anonymous: 30 req/min (no key)
• Free: 120 req/min, 1,000 req/day (with API key)
• Pro: 1,000 req/min, 10,000 req/day (with API key)
• Internal: Unlimited (with API key)

Search Query Parameters

Season & Episode Filtering:

• season=1 — Filter by TV show season number
• episode=5 — Filter by episode number
• Note: Also supports parsing from query text (e.g., q=breaking+bad+S01E05)

Audio & Video Quality:

• audio=atmos — Filter by audio codec (aac, flac, opus, atmos)
• hdr=dolby_vision — Filter by HDR format (hdr10, dolby_vision, hdr10plus, hlg)
• quality=2160p — Filter by resolution (480p, 720p, 1080p, 2160p)

Localization:

• locale=es — Get titles in Spanish (also: fr, de, pt, it, ja, ko, zh, ru, ar)

Response Fields

Content fields:

• hasTorrents (boolean) — Whether content has associated torrents
• maxSeeders (number) — Highest seeder count across all torrents for this content
• backdropUrl (string) — TMDB backdrop image URL
• contentUrl (string) — Relative URL for content detail page

Torrent fields:

• scrapedAt (string, ISO 8601) — Timestamp of last tracker scrape for real-time seeder/leecher counts
• uploadedAt (string, ISO 8601) — When the torrent was first uploaded
• releaseGroup (string) — Release group name (e.g., "YTS", "RARBG")
• isProper (boolean) — Whether this is a PROPER release (fix for previous release issues)
• isRepack (boolean) — Whether this is a REPACK (re-packaged due to issues)
• isRemastered (boolean) — Whether this is a remastered release

Credits Response Schema

{
  "contentId": 1,
  "director": "Christopher Nolan",
  "cast": [
    {
      "name": "Leonardo DiCaprio",
      "character": "Cobb",
      "profileUrl": "https://image.tmdb.org/t/p/w185/..."
    }
  ]
}

Returns contentId, director name, and up to 10 cast members. Param: id (path, required)

Track Request Schema

{
  "infoHash": "aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
  "action": "magnet"
}

Method: POST. Actions: magnet, torrent_download, copy. Response: {"ok": true}

Search Analytics Response Schema

{
  "period": { "days": 7, "since": "2026-02-06T00:00:00Z" },
  "summary": { "totalSearches": 15420, "uniqueQueries": 8730, "avgResults": 12.3, "zeroResultSearches": 120, "webSearches": 10000, "apiSearches": 5420 },
  "topQueries": [{ "query": "dune", "count": 342, "avgResults": 15.2 }],
  "zeroResultQueries": [{ "query": "obscure title", "count": 5 }],
  "dailyVolume": [{ "date": "2026-02-13", "total": 2200, "web": 1500, "api": 700 }]
}

Params: days (1-90, default 7), limit (1-100, default 20). Requires pro tier API key.

Error Responses

Status	Meaning
400	Invalid parameters (missing q, bad genre, etc.)
404	Torrent file not found (torrent endpoint only)
429	Rate limited
500	Internal server error

Rate Limits

Endpoint	Limit
/api/v1/search	30/min
/api/v1/autocomplete	60/min
/api/v1/popular	30/min
/api/v1/recent	30/min
/api/v1/content/{id}/credits	30/min
/api/v1/stats	10/min
/api/v1/torrent	20/min
/api/v1/track	60/min
/api/v1/search-analytics	10/min

Torrent Download Integration

Using magnetUrl with Transmission

# Search and add best torrent to Transmission
RESULT=$(curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=inception&type=movie&sort=seeders&limit=1")
MAGNET=$(echo "$RESULT" | jq -r '.results[0].torrents[0].magnetUrl')
transmission-remote -a "$MAGNET"

Using magnetUrl with aria2

RESULT=$(curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=inception&sort=seeders&limit=1")
MAGNET=$(echo "$RESULT" | jq -r '.results[0].torrents[0].magnetUrl')
aria2c "$MAGNET" --dir=~/Downloads

Downloading .torrent files

# Get info hash from search result
INFO_HASH=$(echo "$RESULT" | jq -r '.results[0].torrents[0].infoHash')

# Download .torrent file
curl -o "movie.torrent" "https://torrentclaw.com/api/v1/torrent/$INFO_HASH"

# The file includes a descriptive filename in Content-Disposition header:
# TorrentClaw.com-Inception-1080p-EN.torrent

Data Sources

Source	Content	Notes
YTS	Movies	High quality, IMDb IDs
EZTV	TV Shows	Episode torrents, IMDb IDs
Knaben	Mixed	Meta-search aggregator
Prowlarr	Mixed	Indexer aggregator
Bitmagnet	Mixed	DHT discovery
Torrentio	Mixed	Stremio ecosystem
DonTorrent	Mixed	Spanish content
Torrents.csv	Mixed	Open dataset
TMDB	Metadata	Posters, genres, translations