{"openapi":"3.1.0","info":{"title":"TorrentClaw API","version":"1.4.0","description":"Torrent search engine API. Aggregates movies and TV shows from 30+ international sources, enriches them with TMDB metadata, scores each torrent for quality (0-100), and verifies releases via TrueSpec file analysis (codec, resolution, HDR, audio tracks, subtitles). Beyond the JSON API, TorrentClaw also exposes a Torznab feed (Sonarr/Radarr), RSS feeds, a Stremio addon, and an MCP server.\n\n**Authentication:** API key sent via `Authorization: Bearer <key>` header (preferred) or `?api_key=<key>` query param. Public read endpoints work anonymously with low rate limits.\n\n**Tiers:** `anonymous` (no key), `free` (registered user), `pro` (paid). A free API key unlocks the Torznab feed; PRO unlocks debrid integration, stream metadata, custom RSS, and larger payloads.\n\n**Rate limits:** per-endpoint, IP-based for anonymous traffic, key-based for authenticated traffic. 429 responses include `Retry-After`.","contact":{"name":"TorrentClaw","url":"https://herecomesaconsequence.com"},"license":{"name":"Terms of Service","url":"https://herecomesaconsequence.com/terms"}},"externalDocs":{"description":"LLM-friendly summary, MCP usage, and ChatGPT plugin notes","url":"https://herecomesaconsequence.com/llms.txt"},"servers":[{"url":"https://herecomesaconsequence.com","description":"Production"}],"tags":[{"name":"Discovery","description":"Search, autocomplete, popular, recent, trending, upcoming, streaming Top 10, and collections."},{"name":"Torrents","description":"Direct .torrent file download by info hash, proxied through cache services."},{"name":"Streaming","description":"Stream metadata for opening an HLS session against the user's own unarr agent. PRO tier."},{"name":"Stats","description":"Aggregator-wide statistics (content, torrents, ingestion log)."},{"name":"Sonarr/Radarr","description":"Newznab/Torznab-compatible feed for *arr clients. Requires an API key (free tier)."},{"name":"Debrid","description":"Stateless debrid integration. Headers `X-Debrid-Provider` and `X-Debrid-Key` carry user creds; TorrentClaw never stores them. PRO tier."}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]},{}],"paths":{"/api/v1/search":{"get":{"operationId":"searchContent","tags":["Discovery"],"summary":"Search or browse movies and TV shows","description":"Full-text search across titles with advanced filtering, **or** filter-only browsing (discover mode) when `q` is omitted.\n\nReturns content with posters, ratings, streaming availability (when `streaming_country` is set), and associated torrents sorted by quality score. Supports localized titles in 11 languages and TrueSpec-verified-only filtering via `verified=true`.\n\n**Discover mode** — omit `q` and pass at least one filter to browse the catalog by facets alone, e.g. `?genre=Action&type=movie&year_min=2020&min_rating=7&sort=rating&limit=50`. Results are ordered by the requested `sort` (PRO) or by popularity, and titles with torrents rank above those without. At least one narrowing filter is required: a request with neither `q` nor a filter returns 400. Note that `streaming_country` and `locale` do NOT count — they enrich the rows returned (watch providers, translations) rather than narrowing them. `country` DOES count: it filters by country of origin.\n\n**Seasons and episode counts (TV)** — opt-in via the `include` parameter (its description below has the full contract):\n\n- `?q=breaking+bad&include=seasons` → each TV result gets `seasons: [{ \"season\": 1, \"episodeCount\": 7, \"posterUrl\": \"…\" }, …]`.\n- `?imdbid=tt0903747&include=episodes` → additionally the per-episode list.\n\n**Season packs** — a torrent with `season` set and `episode: null` is a season pack; `packEpisodes` lists the episodes it actually contains. The `episode` filter returns that episode's own releases only, so to find packs query by `season` alone and check `packEpisodes`.","parameters":[{"name":"q","in":"query","required":false,"description":"Search query — movie or TV show title (max 200 characters). Also accepts an exact id: pass a bare IMDB id (`tt0830361`) or `tmdb:<id>` (`tmdb:3868`) to bypass full-text search and match a single title. Optional when `imdbid`/`tmdbid` is supplied, or when at least one filter is set (discover mode).","schema":{"type":"string","maxLength":200}},{"name":"imdbid","in":"query","description":"Exact IMDB id lookup (e.g. `tt0830361`; a bare numeric id is prefixed with `tt` automatically). Takes precedence over `q`. Torznab parity.","schema":{"type":"string"}},{"name":"tmdbid","in":"query","description":"Exact TMDB id lookup (e.g. `3868`). Takes precedence over `q` when `imdbid` is absent. Torznab parity.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Content type filter","schema":{"type":"string","enum":["movie","show"]}},{"name":"genre","in":"query","description":"Genre filter (exact match)","schema":{"type":"string","enum":["Action","Adventure","Animation","Anime","Donghua","Aeni","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"]}},{"name":"year_min","in":"query","description":"Minimum release year (e.g. 2020)","schema":{"type":"integer"}},{"name":"year_max","in":"query","description":"Maximum release year (e.g. 2025)","schema":{"type":"integer"}},{"name":"min_rating","in":"query","description":"Minimum IMDb/TMDB rating threshold (0-10)","schema":{"type":"number","minimum":0,"maximum":10}},{"name":"quality","in":"query","description":"Torrent video resolution filter — EXACT match. For a range, use quality_min / quality_max instead (all three combine with AND).","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]}},{"name":"quality_min","in":"query","description":"Lowest acceptable resolution (inclusive). Combine with quality_max for a range: quality_min=720p&quality_max=1080p returns 720p and 1080p only. Torrents whose resolution is unknown are excluded whenever either bound is set.","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]}},{"name":"quality_max","in":"query","description":"Highest acceptable resolution (inclusive). quality_max=1080p skips 4K. An inverted range (min above max) returns no results rather than being ignored.","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]}},{"name":"size_min_gb","in":"query","description":"Minimum torrent size in GiB (1 GiB = 1024³ bytes — the number torrent clients show). Fractions allowed (e.g. 0.7). Torrents with an unknown size are excluded whenever either size bound is set.","schema":{"type":"number","exclusiveMinimum":0,"example":1.5}},{"name":"size_max_gb","in":"query","description":"Maximum torrent size in GiB (1 GiB = 1024³ bytes). size_max_gb=10 returns only releases under 10 GiB. Fractions allowed.","schema":{"type":"number","exclusiveMinimum":0,"example":10}},{"name":"lang","in":"query","description":"Torrent audio language — ISO 639 code (e.g. 'en', 'es', 'ta'), optionally with a region: 'es-ES' / 'es-419' (Castilian / Latin American), 'pt-BR' / 'pt-PT', 'fr-FR' / 'fr-CA', 'en-US' / 'en-GB'. A bare code ('es') matches every regional variant; a variant matches only itself.","schema":{"type":"string","pattern":"^[a-z]{2,3}(-(?:\\d{3}|[A-Za-z]{2}))?$"}},{"name":"subs","in":"query","description":"Subtitle language filter — ISO 639 code (e.g. 'en', 'es'), optionally with a region ('es-ES', 'es-419', 'pt-BR'). A bare code matches every regional variant; a variant matches only itself. Combines TrueSpec verified data with raw title parsing for broader coverage.","schema":{"type":"string","pattern":"^[a-z]{2,3}(-(?:\\d{3}|[A-Za-z]{2}))?$"}},{"name":"audio","in":"query","description":"Audio codec filter — substring match (e.g. 'aac', 'flac', 'opus', 'atmos')","schema":{"type":"string"}},{"name":"hdr","in":"query","description":"HDR format filter — matched case-insensitively against the release's HDR tag. Accepted: 'hdr', 'hdr10', 'hdr10+', 'dv', 'dv+hdr10', 'dv+hlg', 'hlg'.","schema":{"type":"string","enum":["hdr","hdr10","hdr10+","dv","dv+hdr10","dv+hlg","hlg"]}},{"name":"country","in":"query","description":"FILTERS by country of origin — ISO 3166-1 alpha-2 (e.g. 'JP', 'FR', 'US'). Co-productions match on any of their countries, and each result carries `originCountry`. DEPRECATED BEHAVIOUR: this parameter used to select the streaming-availability country. It still does so while `streaming_country` is absent, and those responses include a `deprecation` field — pass `streaming_country` instead before that fallback is removed.","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"streaming_country","in":"query","description":"ISO 3166-1 country code — when provided, includes streaming/watch provider availability in the response (e.g. 'US', 'ES', 'GB'). Does NOT filter the result set.","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"include","in":"query","description":"Comma-separated opt-in extras. Does NOT filter the result set.\n\n- `seasons` — attaches a per-season summary to every TV result: season number, `episodeCount` and season poster.\n- `episodes` — additionally attaches the full per-episode list (name, overview, air date, runtime, still, rating). Because the episode data can be several MB for a long-running series, it is only attached on single-title id lookups (`imdbid`/`tmdbid`); on a multi-result search the response falls back to the `seasons` summary.\n\nSeason data comes from TMDB and is not yet populated for every show — when it is missing the `seasons` key is OMITTED rather than returned as an empty array, so absent means 'unknown', never 'this show has no seasons'.","schema":{"type":"array","items":{"type":"string","enum":["seasons","episodes"]},"example":["seasons"]},"style":"form","explode":false},{"name":"locale","in":"query","description":"Language for title/overview/poster translations (e.g. 'es', 'fr', 'de'). Falls back to English if unavailable.","schema":{"type":"string","pattern":"^[a-z]{2}$"}},{"name":"availability","in":"query","description":"Filter by torrent availability: 'available' = has torrents, 'unavailable' = no torrents","schema":{"type":"string","enum":["all","available","unavailable"],"default":"all"}},{"name":"sort","in":"query","description":"Sort order for results. PRO only: without a PRO API key the parameter is ignored and results come back in relevance order. Titles with torrents always rank first, and for a non-relevance sort title matches rank above overview-only matches.","schema":{"type":"string","enum":["relevance","seeders","year","rating","added"],"default":"relevance"}},{"name":"page","in":"query","description":"Page number (starts at 1)","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1}},{"name":"limit","in":"query","description":"Results per page","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"verified","in":"query","description":"Filter by TrueSpec verified torrents only. When true, only returns content with at least one torrent that has been scanned and verified by TrueSpec (audio, video, and subtitle metadata confirmed).","schema":{"type":"boolean","default":false}},{"name":"nl","in":"query","description":"Natural-language interpretation control. By default (omitted) the query is interpreted by an LLM only when the ordinary search finds nothing, so a plain title lookup is never slowed down. Set to \"1\" to force interpretation up-front (for descriptive queries such as \"something scary but not gory\"), or \"0\" to disable it entirely. Interpretation is subject to a per-plan daily quota; the response's `nlSearch` object reports which path was taken.","schema":{"type":"string","enum":["0","1"]}},{"name":"season","in":"query","description":"TV show season number filter (e.g. 1, 2). Only applies to shows.","schema":{"type":"integer","minimum":0}},{"name":"episode","in":"query","description":"TV show episode number filter (e.g. 5). Only applies to shows. Requires season to be set. Returns that episode's own releases only — season packs are excluded; query by `season` alone and read each pack's `packEpisodes` to find the ones that contain it.","schema":{"type":"integer","minimum":0}},{"name":"votes_min","in":"query","description":"Minimum TMDB vote count tier (popularity proxy). Allowed: 1000, 10000, 100000.","schema":{"type":"integer","enum":[1000,10000,100000]}},{"name":"codec","in":"query","description":"Video codec filter (multi-value, comma-separated). Allowed: x264, x265, h264, h265, av1, hevc, xvid, vp9.","schema":{"type":"string","example":"x265,av1"}},{"name":"audio_codec","in":"query","description":"Audio codec filter (multi-value, comma-separated). Allowed: dts, truehd, atmos, eac3, ac3, aac, mp3, flac, opus, dd, ddp.","schema":{"type":"string","example":"atmos,dts"}},{"name":"audio_ch","in":"query","description":"Audio channels filter. 2 = stereo, 6 = 5.1 surround, 8 = 7.1 surround.","schema":{"type":"integer","enum":[1,2,6,8]}},{"name":"source","in":"query","description":"Source type filter (multi-value, comma-separated). Allowed: bluray, remux, webdl, webrip, hdtv, dvdrip, brrip, cam, hdcam.","schema":{"type":"string","example":"bluray,remux"}},{"name":"release_group","in":"query","description":"Release group filter (multi-value, comma-separated). Exact match. Allowed characters: alphanumeric plus . _ -","schema":{"type":"string","example":"YIFY,RARBG"}}],"responses":{"200":{"description":"Search results with content metadata and torrents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid request parameters — including a request with neither `q` nor any narrowing filter. Filters with unrecognised values (e.g. `genre=NotAGenre`, `year_min=abc`) are ignored and do not satisfy the discover-mode requirement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/comments":{"get":{"operationId":"listComments","tags":["Discovery"],"summary":"List public comments for a content","description":"Returns visible top-level comments for a given content (movie or TV show). Replies (threaded) are not exposed via the public list endpoint.","parameters":[{"name":"content_id","in":"query","required":true,"description":"Internal content id","schema":{"type":"integer","minimum":1}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Page size","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"sort","in":"query","description":"Sort order. 'top' = net score (upvotes - downvotes); 'recent' = newest first.","schema":{"type":"string","enum":["top","recent"],"default":"top"}}],"responses":{"200":{"description":"Paginated list of visible comments","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid contentId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/autocomplete":{"get":{"operationId":"autocomplete","tags":["Discovery"],"summary":"Autocomplete search suggestions","description":"Returns up to 8 content suggestions matching the query prefix. Only returns content that has torrents. Sorted by TMDB popularity.","parameters":[{"name":"q","in":"query","required":true,"description":"Search prefix (2-200 characters)","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"locale","in":"query","required":false,"description":"Locale for localized collection names (e.g. 'es', 'fr')","schema":{"type":"string"}}],"responses":{"200":{"description":"Autocomplete suggestions (content and collections)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}}}}},"/api/v1/mirrors":{"get":{"operationId":"listMirrors","tags":["Discovery"],"summary":"List TorrentClaw mirrors and alternate access methods","description":"Public, unauthenticated discovery endpoint. Returns the canonical mirror list (clearnet domains, Tor hidden service, out-of-band channels, and off-domain static fallbacks). Long-running agents (e.g. unarr CLI) should call this periodically so they survive takedowns of the primary domain.","responses":{"200":{"description":"Mirror list","content":{"application/json":{"schema":{"type":"object","required":["revision","mirrors","updatedAt"],"properties":{"revision":{"type":"integer","description":"Bumped when the shape of the response meaningfully changes."},"mirrors":{"type":"array","items":{"type":"object","required":["url","label","kind","primary"],"properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string"},"kind":{"type":"string","enum":["clearnet","tor"]},"primary":{"type":"boolean"}}}},"tor":{"type":"object","nullable":true,"properties":{"url":{"type":"string"},"label":{"type":"string"}}},"channels":{"type":"array","items":{"type":"object","required":["url","label"],"properties":{"url":{"type":"string"},"label":{"type":"string"}}}},"staticFallbacks":{"type":"array","items":{"type":"object","required":["url","label"],"properties":{"url":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}}},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/raffle/current":{"get":{"deprecated":true,"operationId":"getCurrentRaffle","tags":["Discovery"],"summary":"Current monthly raffle period summary (GONE — raffle closed)","description":"GONE. The monthly raffle closed on 2026-08-24 and this endpoint now always answers 404; there is no current period and none will be created. Documented only because the route file still exists — it is removed with the rest of the raffle code. For the draws that were held, use the ledger and verify endpoints below, which keep working permanently.","responses":{"404":{"description":"Always — the raffle is closed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/raffle/{slug}/ledger":{"get":{"deprecated":true,"operationId":"getRaffleLedger","tags":["Discovery"],"summary":"Anonymous coupon ledger for a raffle period","description":"Public, fully anonymous list of coupons for a period: opaque publicId + reason + count only. Never exposes user identity. Used to publicly audit the frozen coupon set. No new periods will be created: the raffle closed on 2026-08-24. Historical periods stay queryable permanently.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Period slug, YYYY-MM."}],"responses":{"200":{"description":"Anonymous coupon ledger","content":{"application/json":{"schema":{"type":"object","required":["slug","ledger","totalCoupons"],"properties":{"slug":{"type":"string"},"totalCoupons":{"type":"integer"},"ledger":{"type":"array","items":{"type":"object","required":["publicId","reason","count"],"properties":{"publicId":{"type":"string"},"reason":{"type":"string","enum":["base","pro","pro_plus","referral"]},"count":{"type":"integer"},"claimCommit":{"type":"string","nullable":true,"description":"sha256(publicId ':' secret) — public winner-proof commit, set at freeze."}}}}}}}}},"404":{"description":"Period not found"}}}},"/api/v1/raffle/{slug}/verify":{"get":{"deprecated":true,"operationId":"getRaffleVerification","tags":["Discovery"],"summary":"Provably-fair draw verification record","description":"Public, immutable verification record for a drawn period: commitment hash, drand seed reference + value, selection algorithm, and the winning coupon. Everything a third party needs to recompute the winner without trusting the server. 404 until the period is drawn. No new draws will happen: the raffle closed on 2026-08-24. Past draws stay verifiable permanently.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Period slug, YYYY-MM."}],"responses":{"200":{"description":"Draw verification record","content":{"application/json":{"schema":{"type":"object","required":["slug","commitmentHash","totalCoupons","seedSource","seedRef","seedValue","winnerCouponNo","winnerPublicId","algorithm"],"properties":{"slug":{"type":"string"},"commitmentHash":{"type":"string"},"totalCoupons":{"type":"integer"},"couponListSha256":{"type":"string"},"seedSource":{"type":"string"},"seedRef":{"type":"string"},"seedValue":{"type":"string"},"winnerCouponNo":{"type":"integer"},"winnerPublicId":{"type":"string"},"winnerClaimCommit":{"type":"string","nullable":true,"description":"The winning coupon's public commit. Winner reveals their secret; anyone checks sha256(winnerPublicId ':' secret) === this."},"proofScheme":{"type":"string","description":"How to recompute the winner-proof commit."},"algorithm":{"type":"string"},"drawnAt":{"type":"string","format":"date-time"},"drandUrl":{"type":"string","nullable":true},"prize":{"type":"object","nullable":true,"description":"Anonymous fulfillment record: which prize the winner chose and whether/when it was delivered. No PII.","properties":{"selectedOption":{"type":"string","nullable":true,"enum":["debrid_1yr","lifetime_pro"]},"fulfilled":{"type":"boolean"},"fulfilledAt":{"type":"string","format":"date-time","nullable":true},"fulfillmentRef":{"type":"string","nullable":true}}}}}}}},"404":{"description":"Draw not available yet"}}}},"/api/v1/popular":{"get":{"operationId":"getPopularContent","tags":["Discovery"],"summary":"Get popular movies and TV shows","description":"Returns the most popular content, ranked by swarm size corroborated against TMDB vote counts and on-site views (announced seeder counts alone are trivially inflated by trackers). Only includes content with a poster and at least 1 seeder.","parameters":[{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","minimum":1,"maximum":24,"default":12}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}},{"name":"type","in":"query","description":"Restrict to movies or TV shows. Omit for both.","schema":{"type":"string","enum":["movie","show"]}}],"responses":{"200":{"description":"Popular content list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PopularResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/recent":{"get":{"operationId":"getRecentContent","tags":["Discovery"],"summary":"Get recently added content","description":"Returns the most recently added movies and TV shows to the catalog. Only includes content with a poster.","parameters":[{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","minimum":1,"maximum":24,"default":12}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"Recently added content list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/recently-found":{"get":{"operationId":"getRecentlyFoundRequests","tags":["Discovery"],"summary":"Public catalog of fulfilled content requests","description":"Anonymized list of movies/TV shows that other users requested and we hunted across torrent, Debrid and Usenet. No auth required. Submitter PII (email, userId, notes) is never returned.","parameters":[{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","minimum":1,"maximum":50,"default":24}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"type","in":"query","description":"Filter by media type","schema":{"type":"string","enum":["movie","show"]}}],"responses":{"200":{"description":"Anonymized recently-found content list","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/upcoming":{"get":{"operationId":"getUpcomingContent","tags":["Discovery"],"summary":"Get upcoming movie and TV show releases","description":"Returns upcoming movies and TV shows ordered by TMDB popularity. Includes titles with future release dates from the next 6 months.","parameters":[{"name":"limit","in":"query","description":"Number of items to return","schema":{"type":"integer","minimum":1,"maximum":50,"default":24}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"type","in":"query","description":"Filter by content type","schema":{"type":"string","enum":["all","movie","show"],"default":"all"}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"Upcoming content list","content":{"application/json":{"schema":{"type":"object"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/torrent/{infoHash}":{"get":{"operationId":"downloadTorrentFile","tags":["Torrents"],"summary":"Download .torrent file","description":"Proxies the .torrent file for a given info hash through multiple torrent cache services. Returns branded filename with content metadata. Cached for 24 hours.","parameters":[{"name":"infoHash","in":"path","required":true,"description":"40-character hex SHA1 info hash","schema":{"type":"string","pattern":"^[a-fA-F0-9]{40}$"}},{"name":"t","in":"query","description":"Signed download token obtained from the content page. Required for requests without an API key.","schema":{"type":"string"}}],"responses":{"200":{"description":"Torrent file download","content":{"application/x-bittorrent":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Disposition":{"description":"Branded filename (e.g. TorrentClaw.com-Title-1080p.torrent)","schema":{"type":"string"}}}},"400":{"description":"Invalid info hash format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Download token required or invalid (requests without API key must include a valid token)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Torrent file not available from any cache source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stream/{infoHash}":{"get":{"operationId":"getStreamMetadata","tags":["Streaming"],"summary":"Stream metadata (PRO)","description":"Returns torrent metadata (magnet, infoHash, sizeBytes, title) plus signalEndpoint — the POST URL clients use to open an HLS session against the user's own unarr agent. TorrentClaw never relays content bytes. Requires the PRO tier.","parameters":[{"name":"infoHash","in":"path","required":true,"description":"40-character hex SHA1 info hash","schema":{"type":"string","pattern":"^[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"Stream metadata payload","content":{"application/json":{"schema":{"type":"object","required":["infoHash","rawTitle","magnet","signalEndpoint"],"properties":{"infoHash":{"type":"string"},"title":{"type":"string","nullable":true},"rawTitle":{"type":"string"},"sizeBytes":{"type":"integer","nullable":true},"magnet":{"type":"string","description":"magnet:? URI populated with the configured tracker list"},"signalEndpoint":{"type":"string","description":"POST { infoHash } here to open the daemon HLS session"}}}}}},"400":{"description":"Invalid info hash format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication required (anonymous request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"PRO tier required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Torrent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/trending":{"get":{"operationId":"getTrending","tags":["Discovery"],"summary":"Get trending content","description":"Returns trending movies and TV shows based on recent click activity and seeder counts. Supports daily, weekly, and monthly periods.","parameters":[{"name":"period","in":"query","description":"Trending period","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"}},{"name":"limit","in":"query","description":"Results per page","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2,3}$"}}],"responses":{"200":{"description":"Trending content list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PopularResponse"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/collections":{"get":{"operationId":"getCollections","tags":["Discovery"],"summary":"List movie collections (sagas)","description":"Returns popular movie collections/sagas sorted by total seeders. Each collection groups related movies (e.g. 'The Lord of the Rings', 'Fast & Furious').","parameters":[{"name":"limit","in":"query","description":"Results per page","schema":{"type":"integer","minimum":1,"maximum":48,"default":24}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"Collections list with movie counts and total seeders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}}}}},"/api/v1/collections/{id}":{"get":{"operationId":"getCollectionDetail","tags":["Discovery"],"summary":"Get collection detail with movies","description":"Returns a specific collection with all its movies, including posters, ratings, and torrent availability.","parameters":[{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"integer"}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"Collection detail with movies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionDetail"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/streaming-top":{"get":{"operationId":"getStreamingTop","tags":["Discovery"],"summary":"Get streaming service Top 10 rankings","description":"Returns Top 10 movies or series from a streaming service (Netflix, Prime Video, Disney+, Apple TV+, Crunchyroll) for a specific country. Includes torrent availability and content matching.","parameters":[{"name":"service","in":"query","description":"Streaming service","schema":{"type":"string","enum":["netflix","prime","disney","apple","crunchyroll"],"default":"netflix"}},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 country code","schema":{"type":"string","pattern":"^[A-Z]{2}$","default":"US"}},{"name":"show_type","in":"query","description":"Type of content","schema":{"type":"string","enum":["movie","series"],"default":"movie"}},{"name":"locale","in":"query","description":"Language for localized titles (e.g. 'es', 'fr')","schema":{"type":"string","pattern":"^[a-z]{2}$"}}],"responses":{"200":{"description":"Top 10 ranking list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StreamingTopItem"}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stats":{"get":{"operationId":"getStats","tags":["Stats"],"summary":"Get aggregator statistics","description":"Returns content counts (movies/shows), torrent counts by source, and recent ingestion history. Returns empty stats on error (never 500).","responses":{"200":{"description":"Aggregator statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}}}}},"/api/v1/debrid/check-cache":{"post":{"operationId":"debridCheckCache","tags":["Debrid"],"summary":"Batch-check torrent cache on a debrid service","description":"Check if torrents are instantly available (cached) on the user's debrid service. Requires X-Debrid-Provider and X-Debrid-Key headers. Pro tier required.","parameters":[{"name":"X-Debrid-Provider","in":"header","required":true,"schema":{"type":"string","enum":["real-debrid","alldebrid","torbox","premiumize","torrin"]},"description":"Debrid service provider"},{"name":"X-Debrid-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Debrid service API key/token"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"infoHashes":{"type":"array","items":{"type":"string","pattern":"^[a-fA-F0-9]{40}$"},"minItems":1,"maxItems":200,"description":"Array of 40-char hex info hashes to check"}},"required":["infoHashes"]}}}},"responses":{"200":{"description":"Cache status for each hash","content":{"application/json":{"schema":{"type":"object","properties":{"cached":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Map of infoHash → cached status"}},"required":["cached"]}}}},"400":{"description":"Missing headers or invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid debrid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The provider does not know this id. Only reachable for clients that send `X-TC-Client-Features: provider-4xx`; without it this is 502.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"The debrid provider failed us (down, unreachable, or an unparseable answer). Retryable. Deliberately NOT 5xx: a 5xx means TorrentClaw itself failed, and emitting one here used to mark our own replicas dead in the reverse proxy's failure accounting. Served only to clients that send `X-TC-Client-Features: provider-4xx`; without that header the same condition is reported as 502 (see below).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Debrid service rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"The provider refuses this specific release. NOT an outage — retrying will not help. Only reachable for clients that send `X-TC-Client-Features: provider-4xx`; without it this is 502.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"LEGACY spelling of the 424 above, kept for clients that predate the `X-TC-Client-Features: provider-4xx` handshake and treat only 5xx as retryable. Send that header to receive 424 instead. New integrations should treat 424 and 502 identically: both mean the upstream debrid provider failed and the request is worth retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/debrid/add-magnet":{"post":{"operationId":"debridAddMagnet","tags":["Debrid"],"summary":"Send a torrent to a debrid service","description":"Add a magnet link to the user's debrid service for download. Returns the debrid torrent ID and whether it was instantly cached. Requires X-Debrid-Provider and X-Debrid-Key headers. Pro tier required.","parameters":[{"name":"X-Debrid-Provider","in":"header","required":true,"schema":{"type":"string","enum":["real-debrid","alldebrid","torbox","premiumize","torrin"]},"description":"Debrid service provider"},{"name":"X-Debrid-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Debrid service API key/token"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"infoHash":{"type":"string","pattern":"^[a-fA-F0-9]{40}$","description":"40-char hex info hash of the torrent"}},"required":["infoHash"]}}}},"responses":{"200":{"description":"Magnet added successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Torrent ID on the debrid service"},"cached":{"type":"boolean","description":"Whether the torrent was instantly available"},"name":{"type":"string","description":"Torrent name"}},"required":["id","cached"]}}}},"400":{"description":"Missing headers or invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid debrid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The provider does not know this id. Only reachable for clients that send `X-TC-Client-Features: provider-4xx`; without it this is 502.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"The debrid provider failed us (down, unreachable, or an unparseable answer). Retryable. Deliberately NOT 5xx: a 5xx means TorrentClaw itself failed, and emitting one here used to mark our own replicas dead in the reverse proxy's failure accounting. Served only to clients that send `X-TC-Client-Features: provider-4xx`; without that header the same condition is reported as 502 (see below).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Debrid service rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"The provider refuses this specific release. NOT an outage — retrying will not help. Only reachable for clients that send `X-TC-Client-Features: provider-4xx`; without it this is 502.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"LEGACY spelling of the 424 above, kept for clients that predate the `X-TC-Client-Features: provider-4xx` handshake and treat only 5xx as retryable. Send that header to receive 424 instead. New integrations should treat 424 and 502 identically: both mean the upstream debrid provider failed and the request is worth retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/truespec/lookup":{"post":{"operationId":"truespecLookup","tags":["Sonarr/Radarr"],"summary":"K-anonymous TrueSpec verification lookup (for the *arr reconciler)","description":"Send infohash PREFIXES (exactly 5 hex characters), never full infohashes; the response lists every torrent in those buckets (~6 per prefix) with its verification status and the caller filters locally, so TorrentClaw never learns the exact library. Used by `truespec-arr-sync.sh` to put the Internal indexer flag on files Sonarr/Radarr already imported. Requires an API key (free tier).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prefixes":{"type":"array","items":{"type":"string","pattern":"^[a-fA-F0-9]{5}$"},"minItems":1,"maxItems":100,"description":"5-hex-character infohash prefixes"}},"required":["prefixes"]}}}},"responses":{"200":{"description":"Verification status of every torrent in the requested buckets","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"infohash":{"type":"string"},"verified":{"type":"boolean","description":"Scanned from the real file and its resolution is not overstated"},"mismatch":{"type":"boolean","description":"Scanned and the name claims more resolution than the file has"},"scannedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"400":{"description":"Missing or malformed prefixes"},"401":{"description":"API key required"}}}},"/api/v1/torznab":{"get":{"operationId":"torznab","tags":["Sonarr/Radarr"],"summary":"Torznab-compatible API for Sonarr/Radarr/Prowlarr","description":"Newznab/Torznab API endpoint. Supports t=caps, t=search, t=tvsearch, t=movie. Includes TrueSpec-verified quality attributes. Requires an API key (free tier).","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","enum":["caps","search","tvsearch","movie"]},"description":"Function type"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"imdbid","in":"query","schema":{"type":"string"},"description":"IMDB ID (e.g. tt1234567)"},{"name":"tmdbid","in":"query","schema":{"type":"string"},"description":"TMDB ID"},{"name":"tvdbid","in":"query","schema":{"type":"string"},"description":"TheTVDB ID (Sonarr series/anime matching)"},{"name":"season","in":"query","schema":{"type":"integer"},"description":"Season number"},{"name":"ep","in":"query","schema":{"type":"integer"},"description":"Episode number"},{"name":"cat","in":"query","schema":{"type":"string"},"description":"Comma-separated category IDs (2000=Movies, 5000=TV)"},{"name":"minsize","in":"query","schema":{"type":"integer","minimum":1,"example":1073741824},"description":"Newznab-standard minimum release size, in BYTES (1 GiB = 1073741824). Releases whose size is unknown are excluded when either size bound is set."},{"name":"maxsize","in":"query","schema":{"type":"integer","minimum":1,"example":10737418240},"description":"Newznab-standard maximum release size, in BYTES (10 GiB = 10737418240). Advertised in t=caps, so Prowlarr/Sonarr can push a size cap down to the indexer."},{"name":"quality_min","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension (not newznab-standard, so it is deliberately absent from t=caps): lowest acceptable resolution, inclusive."},{"name":"quality_max","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension: highest acceptable resolution, inclusive. quality_min=720p&quality_max=1080p returns 720p and 1080p only."},{"name":"mismatch","in":"query","schema":{"type":"integer","enum":[0,1],"default":0},"description":"TorrentClaw extension: 1 also returns releases whose name claims MORE resolution than the file really has (a fake upscale TrueSpec detected by scanning it). Hidden by default."},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Max results"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Result offset for pagination"}],"responses":{"200":{"description":"Torznab XML response with torrent results including TrueSpec attributes","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"API key required (anonymous requests are rejected)"}}}},"/api/v1/torznab/api":{"get":{"operationId":"torznabApiAlias","tags":["Sonarr/Radarr"],"summary":"Torznab alias for clients that append /api","description":"Alias of /api/v1/torznab for clients (AIOStreams, some Sonarr configs) that append the Torznab \"API Path\" segment to the base URL. Identical behavior and parameters. Requires an API key (free tier).","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","enum":["caps","search","tvsearch","movie"]},"description":"Function type"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"imdbid","in":"query","schema":{"type":"string"},"description":"IMDB ID (e.g. tt1234567)"},{"name":"tmdbid","in":"query","schema":{"type":"string"},"description":"TMDB ID"},{"name":"tvdbid","in":"query","schema":{"type":"string"},"description":"TheTVDB ID (Sonarr series/anime matching)"},{"name":"season","in":"query","schema":{"type":"integer"},"description":"Season number"},{"name":"ep","in":"query","schema":{"type":"integer"},"description":"Episode number"},{"name":"cat","in":"query","schema":{"type":"string"},"description":"Comma-separated category IDs (2000=Movies, 5000=TV)"},{"name":"minsize","in":"query","schema":{"type":"integer","minimum":1,"example":1073741824},"description":"Newznab-standard minimum release size, in BYTES (1 GiB = 1073741824). Releases whose size is unknown are excluded when either size bound is set."},{"name":"maxsize","in":"query","schema":{"type":"integer","minimum":1,"example":10737418240},"description":"Newznab-standard maximum release size, in BYTES (10 GiB = 10737418240). Advertised in t=caps, so Prowlarr/Sonarr can push a size cap down to the indexer."},{"name":"quality_min","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension (not newznab-standard, so it is deliberately absent from t=caps): lowest acceptable resolution, inclusive."},{"name":"quality_max","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension: highest acceptable resolution, inclusive. quality_min=720p&quality_max=1080p returns 720p and 1080p only."},{"name":"mismatch","in":"query","schema":{"type":"integer","enum":[0,1],"default":0},"description":"TorrentClaw extension: 1 also returns releases whose name claims MORE resolution than the file really has (a fake upscale TrueSpec detected by scanning it). Hidden by default."},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Max results"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Result offset for pagination"}],"responses":{"200":{"description":"Torznab XML response with torrent results including TrueSpec attributes","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"API key required (anonymous requests are rejected)"}}}},"/api/v1/newznab":{"get":{"operationId":"newznab","tags":["Sonarr/Radarr"],"summary":"Newznab-compatible NZB API for Sonarr/Radarr/Prowlarr/NZBHydra2","description":"Usenet sibling of /api/v1/torznab. Serves NZB releases we index from Usenet itself (Spotnet) — no third-party indexer is proxied, so there is no external API key or quota in the path. Supports t=caps, t=search, t=tvsearch, t=movie and t=get (downloads the .nzb). PRO+ tier required, and an API key: a browser session is rejected on this endpoint.","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","enum":["caps","search","tvsearch","movie","get"]},"description":"Function type"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query (matched against the release name)"},{"name":"imdbid","in":"query","schema":{"type":"string"},"description":"IMDB ID (tt1234567 or bare digits)"},{"name":"season","in":"query","schema":{"type":"integer"},"description":"Season number"},{"name":"ep","in":"query","schema":{"type":"integer"},"description":"Episode number"},{"name":"cat","in":"query","schema":{"type":"string"},"description":"Comma-separated category IDs (2000=Movies, 5000=TV)"},{"name":"id","in":"query","schema":{"type":"string"},"description":"t=get only: the release guid to download the .nzb for"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Max results"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Result offset for pagination"},{"name":"tmdbid","in":"query","schema":{"type":"string"},"description":"Accepted for Torznab parity; NZB releases are matched on imdbid, so this is ignored"},{"name":"tvdbid","in":"query","schema":{"type":"string"},"description":"Accepted for Torznab parity; NZB releases are matched on imdbid, so this is ignored"},{"name":"minsize","in":"query","schema":{"type":"integer","minimum":1,"example":1073741824},"description":"Newznab-standard minimum release size, in BYTES (1 GiB = 1073741824). Releases whose size is unknown are excluded when either size bound is set."},{"name":"maxsize","in":"query","schema":{"type":"integer","minimum":1,"example":10737418240},"description":"Newznab-standard maximum release size, in BYTES (10 GiB = 10737418240). Advertised in t=caps."},{"name":"quality_min","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension (not newznab-standard, so it is deliberately absent from t=caps): lowest acceptable resolution, inclusive. Matched against the release's parsed resolution."},{"name":"quality_max","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension: highest acceptable resolution, inclusive. quality_min=720p&quality_max=1080p returns 720p and 1080p only."}],"responses":{"200":{"description":"Newznab XML feed, or the raw .nzb file when t=get","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"API key required (a browser session is not accepted here)"},"403":{"description":"PRO+ tier required"},"404":{"description":"t=get: the NZB is no longer retrievable from Usenet"}}}},"/api/v1/newznab/api":{"get":{"operationId":"newznabApiAlias","tags":["Sonarr/Radarr"],"summary":"Newznab alias for clients that append /api","description":"Alias of /api/v1/newznab for Prowlarr/NZBHydra2 generic-Newznab entries, which append the \"API Path\" segment to the base URL. Identical behavior and parameters. PRO+ tier required, and an API key: a browser session is rejected on this endpoint.","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string","enum":["caps","search","tvsearch","movie","get"]},"description":"Function type"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query (matched against the release name)"},{"name":"imdbid","in":"query","schema":{"type":"string"},"description":"IMDB ID (tt1234567 or bare digits)"},{"name":"season","in":"query","schema":{"type":"integer"},"description":"Season number"},{"name":"ep","in":"query","schema":{"type":"integer"},"description":"Episode number"},{"name":"cat","in":"query","schema":{"type":"string"},"description":"Comma-separated category IDs (2000=Movies, 5000=TV)"},{"name":"id","in":"query","schema":{"type":"string"},"description":"t=get only: the release guid to download the .nzb for"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Max results"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Result offset for pagination"},{"name":"tmdbid","in":"query","schema":{"type":"string"},"description":"Accepted for Torznab parity; NZB releases are matched on imdbid, so this is ignored"},{"name":"tvdbid","in":"query","schema":{"type":"string"},"description":"Accepted for Torznab parity; NZB releases are matched on imdbid, so this is ignored"},{"name":"minsize","in":"query","schema":{"type":"integer","minimum":1,"example":1073741824},"description":"Newznab-standard minimum release size, in BYTES (1 GiB = 1073741824). Releases whose size is unknown are excluded when either size bound is set."},{"name":"maxsize","in":"query","schema":{"type":"integer","minimum":1,"example":10737418240},"description":"Newznab-standard maximum release size, in BYTES (10 GiB = 10737418240). Advertised in t=caps."},{"name":"quality_min","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension (not newznab-standard, so it is deliberately absent from t=caps): lowest acceptable resolution, inclusive. Matched against the release's parsed resolution."},{"name":"quality_max","in":"query","schema":{"type":"string","enum":["480p","720p","1080p","2160p"]},"description":"TorrentClaw extension: highest acceptable resolution, inclusive. quality_min=720p&quality_max=1080p returns 720p and 1080p only."}],"responses":{"200":{"description":"Newznab XML feed, or the raw .nzb file when t=get","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"description":"API key required (a browser session is not accepted here)"},"403":{"description":"PRO+ tier required"}}}},"/api/v1/speed-test":{"get":{"operationId":"getSpeedTestPayload","tags":["Discovery"],"summary":"Bandwidth probe payload","description":"Returns a stream of random bytes of the requested size. Used by the web player to measure client bandwidth before recommending a streaming quality. No auth required; payload is rate-limited at the middleware level.","parameters":[{"name":"size","in":"query","description":"Bytes to download (64 KiB – 4 MiB, default 2 MiB).","schema":{"type":"integer","minimum":65536,"maximum":4194304,"default":2097152}}],"responses":{"200":{"description":"Random byte stream","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"http","scheme":"bearer","description":"API key sent as `Authorization: Bearer <key>`. Obtain a key at https://herecomesaconsequence.com/profile?tab=apikey&utm_source=openapi&utm_medium=integration."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"Alternative to the Authorization header. Pass the API key as the `api_key` query parameter."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"TrueSpec":{"type":"object","description":"TrueSpec scan result — file-level metadata extracted from a sample of the actual torrent contents. Present when the torrent has been scanned successfully.","properties":{"videoCodec":{"type":["string","null"],"description":"Video codec from container (e.g. hevc, h264, av1)"},"videoWidth":{"type":["integer","null"],"description":"Video width in pixels"},"videoHeight":{"type":["integer","null"],"description":"Video height in pixels"},"videoFrameRate":{"type":["number","null"],"description":"Frames per second"},"hdr":{"type":["string","null"],"description":"HDR format detected from the file (e.g. hdr10, hdr10plus, dolby_vision, hlg) — null if SDR"},"audioTracks":{"type":"array","description":"Per-track audio metadata","items":{"type":"object","properties":{"codec":{"type":["string","null"],"description":"Audio codec (e.g. ac3, eac3, dts, truehd)"},"channels":{"type":["integer","null"],"description":"Channel count (e.g. 2, 6, 8)"},"lang":{"type":["string","null"],"description":"ISO 639 language code"},"title":{"type":["string","null"],"description":"Track title from the container"}}}},"subtitleTracks":{"type":"array","description":"Per-track subtitle metadata","items":{"type":"object","properties":{"lang":{"type":["string","null"],"description":"ISO 639 language code"},"format":{"type":["string","null"],"description":"Subtitle format (e.g. subrip, ass, pgs)"},"forced":{"type":["boolean","null"]},"sdh":{"type":["boolean","null"],"description":"True if SDH (subtitles for the deaf and hard of hearing)"}}}}}},"TorrentInfo":{"type":"object","properties":{"infoHash":{"type":"string","description":"40-char hex SHA1 info hash — unique torrent identifier"},"rawTitle":{"type":"string","description":"Original torrent release name"},"quality":{"type":["string","null"],"enum":["480p","720p","1080p","2160p",null],"description":"Video resolution"},"codec":{"type":["string","null"],"description":"Video codec (e.g. x265, h264, av1)"},"sourceType":{"type":["string","null"],"description":"Release source (e.g. BluRay, WEB-DL, HDTV, CAM)"},"sizeBytes":{"type":["string","null"],"description":"File size in bytes (as string for large numbers)"},"seeders":{"type":"integer","description":"Number of active seeders — higher is better for download speed"},"leechers":{"type":"integer","description":"Number of active leechers"},"magnetUrl":{"type":"string","description":"Magnet URI with trackers for direct download"},"torrentUrl":{"type":"string","description":"URL to download the .torrent file via our proxy (e.g. /api/v1/torrent/{infoHash})"},"source":{"type":"string","description":"Data source (yts, eztv, knaben, prowlarr, torrentio, bitmagnet, torrents-csv, dontorrent)"},"qualityScore":{"type":["integer","null"],"description":"Computed quality score 0-100 — based on resolution, source, codec, seeders, and file size"},"uploadedAt":{"type":["string","null"],"format":"date-time","description":"When the torrent was first uploaded"},"languages":{"type":"array","items":{"type":"string"},"description":"ISO 639 audio language codes (auto-detected from title if not provided by source)"},"audioCodec":{"type":["string","null"],"description":"Audio codec (e.g. AAC, DTS, Atmos)"},"hdrType":{"type":["string","null"],"description":"HDR format if present (e.g. HDR10, Dolby Vision)"},"releaseGroup":{"type":["string","null"],"description":"Release group name"},"isProper":{"type":["boolean","null"],"description":"True if this is a PROPER release (fixes issues in prior release)"},"isRepack":{"type":["boolean","null"],"description":"True if this is a REPACK release"},"isRemastered":{"type":["boolean","null"],"description":"True if this is a remastered version"},"season":{"type":["integer","null"],"description":"TV show season number (null for movies)"},"episode":{"type":["integer","null"],"description":"TV show episode number. Null for movies and for season packs (`season` set, `episode` null)."},"packEpisodes":{"type":["array","null"],"items":{"type":"integer"},"description":"Season packs only: the episode numbers the pack actually contains, ascending (e.g. `[1, 2]` for an in-progress season's pack). Read from the scanned file listing, not the release name. Null when the pack has not been scanned yet or its files carry no episode numbers — unknown, not empty — and always null for single-episode torrents and movies."},"verified":{"type":"boolean","description":"True when this torrent has been TrueSpec-scanned successfully (codec/resolution/audio/subs verified against the real file)."},"trueSpec":{"oneOf":[{"$ref":"#/components/schemas/TrueSpec"},{"type":"null"}],"description":"File-level metadata when the torrent has been scanned. Null if not yet scanned."}},"required":["infoHash","rawTitle","seeders","leechers","magnetUrl","torrentUrl","source","languages"]},"SearchStreamingProvider":{"type":"object","description":"Streaming provider as returned in search results","properties":{"providerId":{"type":"integer"},"name":{"type":"string","description":"Provider name (e.g. Netflix, Disney+, Amazon Prime Video)"},"logo":{"type":["string","null"],"description":"Provider logo URL"},"link":{"type":["string","null"],"description":"Deep link to the content on the provider"}},"required":["providerId","name"]},"SearchStreamingAvailability":{"type":"object","description":"Streaming availability grouped by type (in search results)","properties":{"flatrate":{"type":"array","items":{"$ref":"#/components/schemas/SearchStreamingProvider"},"description":"Available via subscription (Netflix, Disney+, etc.)"},"rent":{"type":"array","items":{"$ref":"#/components/schemas/SearchStreamingProvider"},"description":"Available for rental"},"buy":{"type":"array","items":{"$ref":"#/components/schemas/SearchStreamingProvider"},"description":"Available for purchase"},"free":{"type":"array","items":{"$ref":"#/components/schemas/SearchStreamingProvider"},"description":"Available for free with ads"}}},"SeasonSummary":{"type":"object","description":"One season of a TV series. `episodes` is present only when the request asked for `include=episodes` on a single-title id lookup; `episodeCount` is always present, so the count is available without pulling the full episode list.","properties":{"season":{"type":"integer","description":"Season number. 0 is TMDB's 'Specials' season."},"episodeCount":{"type":"integer","description":"Number of episodes TMDB lists for this season"},"posterUrl":{"type":["string","null"],"description":"Season poster (TMDB), when available"},"episodes":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeInfo"},"description":"Per-episode detail. Only with include=episodes on an id lookup. Honours the `locale` param: name/overview come back translated when a translation exists, English otherwise."}},"required":["season","episodeCount"]},"EpisodeInfo":{"type":"object","properties":{"episode":{"type":"integer","description":"Episode number within its season"},"name":{"type":"string","description":"Episode title"},"overview":{"type":["string","null"],"description":"Episode synopsis"},"stillUrl":{"type":["string","null"],"description":"Episode still image (TMDB)"},"airDate":{"type":["string","null"],"description":"Original air date, YYYY-MM-DD"},"runtime":{"type":["integer","null"],"description":"Runtime in minutes"},"voteAverage":{"type":["number","null"],"description":"TMDB rating 0-10"}},"required":["episode","name"]},"SearchResult":{"type":"object","properties":{"id":{"type":"integer","description":"Content ID"},"imdbId":{"type":["string","null"],"description":"IMDb ID (e.g. tt0133093)"},"tmdbId":{"type":["string","null"],"description":"TMDB ID"},"contentType":{"type":"string","enum":["movie","show"]},"title":{"type":"string","description":"Title (localized if locale param provided)"},"titleOriginal":{"type":["string","null"],"description":"Original language title"},"year":{"type":["integer","null"],"description":"Release year"},"overview":{"type":["string","null"],"description":"Plot synopsis (localized if locale param provided)"},"posterUrl":{"type":["string","null"],"description":"TMDB poster URL (localized if locale param provided)"},"backdropUrl":{"type":["string","null"],"description":"TMDB backdrop image URL"},"genres":{"type":["array","null"],"items":{"type":"string"},"description":"Genre names"},"rating":{"type":["string","null"],"description":"Rating 0-10 (e.g. '8.7'), sourced from TMDB. Canonical field."},"ratingImdb":{"type":["string","null"],"deprecated":true,"description":"DEPRECATED — use `rating`. Identical value, kept for backwards compatibility."},"ratingTmdb":{"type":["string","null"],"description":"TMDB rating (e.g. '8.5')"},"contentUrl":{"type":"string","description":"Relative URL to the content detail page (e.g. /movies/inception-2010-1234)"},"hasTorrents":{"type":"boolean","description":"Whether any torrents are available"},"streaming":{"$ref":"#/components/schemas/SearchStreamingAvailability","description":"Only included when the streaming_country param is provided in the search"},"seasons":{"type":"array","items":{"$ref":"#/components/schemas/SeasonSummary"},"description":"TV series only. Included when `include=seasons` (or `include=episodes`) is passed AND season data is known for the show. Omitted — never an empty array — when the show has no TMDB season data yet."},"torrents":{"type":"array","items":{"$ref":"#/components/schemas/TorrentInfo"},"description":"Available torrents sorted by qualityScore descending"}},"required":["id","contentType","title","contentUrl","hasTorrents","torrents"]},"SearchResponse":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching results across all pages"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"required":["total","page","pageSize","results"]},"AutocompleteSuggestion":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"year":{"type":["integer","null"]},"contentType":{"type":"string","enum":["movie","show","collection"]},"posterUrl":{"type":["string","null"]},"movieCount":{"type":"integer","description":"Number of movies in the collection (only present for collection suggestions)"}},"required":["id","title","contentType"]},"AutocompleteResponse":{"type":"object","properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/AutocompleteSuggestion"},"maxItems":8}},"required":["suggestions"]},"PopularItem":{"type":"object","description":"Popular content item ranked by corroborated swarm size","properties":{"id":{"type":"integer"},"title":{"type":"string"},"contentType":{"type":"string","enum":["movie","show"]},"year":{"type":["integer","null"]},"posterUrl":{"type":["string","null"]},"rating":{"type":["string","null"]},"ratingImdb":{"type":["string","null"],"deprecated":true},"ratingTmdb":{"type":["string","null"]},"maxSeeders":{"type":"integer","description":"Maximum seeders across all torrents for this content"}},"required":["id","title","contentType","maxSeeders"]},"PopularResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PopularItem"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}},"required":["items","total","page","pageSize"]},"CollectionListItem":{"type":"object","description":"Movie collection/saga summary","properties":{"id":{"type":"integer"},"tmdbId":{"type":"integer"},"name":{"type":"string","description":"Collection name (localized if locale param provided)"},"posterUrl":{"type":["string","null"],"description":"TMDB poster URL"},"backdropUrl":{"type":["string","null"],"description":"TMDB backdrop URL"},"movieCount":{"type":"integer","description":"Number of movies in the collection"},"totalSeeders":{"type":"integer","description":"Sum of max seeders across all movies"},"partCount":{"type":"integer","description":"Total number of parts in the collection (including unreleased)"}},"required":["id","tmdbId","name","movieCount","totalSeeders","partCount"]},"CollectionListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CollectionListItem"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}},"required":["items","total","page","pageSize"]},"CollectionDetail":{"type":"object","description":"Full collection detail with movies","properties":{"id":{"type":"integer"},"tmdbId":{"type":"integer"},"name":{"type":"string","description":"Collection name (localized if locale param provided)"},"posterUrl":{"type":["string","null"],"description":"TMDB poster URL"},"backdropUrl":{"type":["string","null"],"description":"TMDB backdrop URL"},"movieCount":{"type":"integer","description":"Number of movies in the collection"},"totalSeeders":{"type":"integer","description":"Sum of max seeders across all movies"},"partCount":{"type":"integer","description":"Total number of parts in the collection (including unreleased)"},"overview":{"type":["string","null"],"description":"Collection synopsis (localized if locale param provided)"},"movies":{"type":"array","items":{"$ref":"#/components/schemas/PopularItem"},"description":"Movies in this collection sorted by release year"}},"required":["id","tmdbId","name","movieCount","totalSeeders","partCount","movies"]},"RecentItem":{"type":"object","description":"Recently added content item","properties":{"id":{"type":"integer"},"title":{"type":"string"},"contentType":{"type":"string","enum":["movie","show"]},"year":{"type":["integer","null"]},"posterUrl":{"type":["string","null"]},"rating":{"type":["string","null"]},"ratingImdb":{"type":["string","null"],"deprecated":true},"ratingTmdb":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","description":"When the content was first added to the catalog"}},"required":["id","title","contentType","createdAt"]},"RecentResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RecentItem"}},"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}},"required":["items","total","page","pageSize"]},"StreamingTopItem":{"type":"object","description":"Streaming service Top 10 ranking item with torrent availability","properties":{"rank":{"type":"integer","description":"Position in the Top 10 (1-10)"},"title":{"type":"string","description":"Title (localized if locale param provided and content is matched)"},"imdbId":{"type":["string","null"],"description":"IMDb ID (e.g. tt0133093)"},"tmdbId":{"type":["integer","null"],"description":"TMDB ID"},"contentType":{"type":["string","null"],"enum":["movie","show",null],"description":"Internal content type"},"year":{"type":["integer","null"],"description":"Release year"},"overview":{"type":["string","null"],"description":"Plot synopsis"},"rating":{"type":["string","null"],"description":"Rating on 0-10 scale (e.g. '8.5')"},"posterUrl":{"type":["string","null"],"description":"Poster image URL (API CDN fallback)"},"backdropUrl":{"type":["string","null"],"description":"Backdrop image URL"},"genres":{"type":["array","null"],"items":{"type":"string"},"description":"Genre names"},"streamingLink":{"type":["string","null"],"description":"Deep link to watch on the streaming service"},"contentId":{"type":["integer","null"],"description":"Our content ID if matched (enables linking to detail page)"},"hasTorrents":{"type":"boolean","description":"Whether we have torrents available for this title"},"maxSeeders":{"type":"integer","description":"Maximum seeders across available torrents (0 if no torrents)"},"localPosterUrl":{"type":["string","null"],"description":"Local poster URL via TMDB proxy (preferred over posterUrl when available)"}},"required":["rank","title","hasTorrents","maxSeeders"]},"StatsResponse":{"type":"object","properties":{"content":{"type":"object","properties":{"movies":{"type":"integer"},"shows":{"type":"integer"},"tmdbEnriched":{"type":"integer"}},"required":["movies","shows","tmdbEnriched"]},"torrents":{"type":"object","properties":{"total":{"type":"integer"},"withSeeders":{"type":"integer"},"weeklyIndexed":{"type":"integer","description":"Torrents indexed in the last 7 days (rolling 7×24h, real count)"},"bySource":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["total","withSeeders","weeklyIndexed","bySource"]},"recentIngestions":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"fetched":{"type":"integer"},"new":{"type":"integer"},"updated":{"type":"integer"}},"required":["source","status","startedAt","fetched","new","updated"]}}},"required":["content","torrents","recentIngestions"]}}}}