# TorrentClaw

> Torrent search engine — aggregates movies and TV shows from 30+ international sources, enriches with TMDB metadata, scores quality (0-100), and verifies releases via TrueSpec file analysis. Exposed through a fast JSON API + Torznab + RSS + Stremio addon + MCP server.

## What It Does

TorrentClaw collects torrent metadata from YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, Torrents.csv, DonTorrent, PelisPanda, DivxTotal and more, enriches it with TMDB metadata (posters, genres, translations in 11+ languages, streaming availability per country), scores each torrent for quality, and runs TrueSpec scans on top results to verify resolution/codec/HDR/audio/subtitles against the actual file.

Public read endpoints work anonymously (low rate limits). Send an API key as `Authorization: Bearer <key>` or `?api_key=<key>` for higher quotas. Tiers: `anonymous`, `free`, `pro`. PRO unlocks Torznab, debrid integration, custom RSS, larger result sets, and the Stremio addon.

## API Endpoints (`/api/v1`)

### Discovery
- `GET /api/v1/search?q=...` — Search movies/shows. Filters: `type`, `genre`, `year_min`, `year_max`, `min_rating`, `quality`, `lang`, `subs`, `audio`, `hdr`, `country`, `locale`, `availability`, `sort`, `season`, `episode`, `verified`, `page`, `limit` (1-50)
- `GET /api/v1/autocomplete?q=...` — Typeahead suggestions (min 2 chars, max 8 results)
- `GET /api/v1/popular?limit=12&page=1&locale=...` — Popular content ranked by community engagement
- `GET /api/v1/recent?limit=12&page=1&locale=...` — Recently added content
- `GET /api/v1/trending?period=daily|weekly|monthly` — Trending content based on click activity + seeders
- `GET /api/v1/upcoming?type=all|movie|show&limit=24` — Upcoming releases (next ~6 months) ordered by TMDB popularity
- `GET /api/v1/streaming-top?service=netflix|prime|disney|apple|crunchyroll&country=US&show_type=movie|series` — Top 10 per streaming service per country, with torrent availability
- `GET /api/v1/collections?limit=24` — Movie collections/sagas ranked by total seeders
- `GET /api/v1/collections/{id}` — Collection detail with all titles

### Torrents
- `GET /api/v1/torrent/{infoHash}` — Download .torrent file by info hash (40 hex chars, cached 24h, proxied through cache services)

### Stats & Health
- `GET /api/v1/stats` — Aggregator stats (content counts, torrent counts by source, recent ingestions)
- `GET /api/v1/tracker-stats` — Live chihaya tracker stats (uptime, announces, completed, active swarms). No auth.

### Sonarr / Radarr (PRO)
- `GET /api/v1/torznab?t=caps` — Newznab/Torznab capabilities
- `GET /api/v1/torznab?t=search&q=...&imdbid=...&tmdbid=...&season=&ep=&cat=2000,5000` — Torznab feed with TrueSpec quality tags `[TC-87]`, `[TrueSpec]`, `[REAL-720p]` for Sonarr/Radarr Custom Formats

### Debrid (PRO, stateless)
Pass user's debrid creds per request via headers `X-Debrid-Provider` (`real-debrid`, `alldebrid`, `torbox`, `premiumize`) and `X-Debrid-Key`.
- `POST /api/v1/debrid/check-cache` — Body `{ "infoHashes": ["..."] }` (1-200). Returns which hashes are instantly cached.
- `POST /api/v1/debrid/add-magnet` — Body `{ "infoHash": "..." }`. Adds magnet to user's debrid, returns torrent id + cache status.

## RSS Feeds (`/api/rss`)
- `GET /api/rss/popular` — Top torrents by seeders (10 anon / 50 with key)
- `GET /api/rss/recent` — Newly indexed torrents (10 anon / 50 with key)
- `GET /api/rss/search?q=...&type=&quality=&lang=&limit=` — Search RSS
- `GET /api/rss/custom?q=...&type=&quality=&lang=&genre=&min_rating=&verified=true&limit=` — PRO custom feed with advanced filters

## Stremio Addon

Self-configuring addon — paste manifest URL into Stremio.

- `GET /api/stremio/manifest.json` — Anonymous manifest (free streams)
- `GET /api/stremio/<base64-config>/manifest.json` — Configured manifest (filters: quality, languages, debrid, etc.)
- `GET /api/stremio/d/<deviceToken>/manifest.json` — Device-paired manifest (TV / split-account flow)
- Catalogs and `/stream/<type>/<imdb>.json` follow the same prefix pattern.

PRO unlocks debrid, larger stream lists (50 vs 15), and verified-only filters.

## Other Useful Endpoints
- `GET /api/openapi.json` — OpenAPI 3.1 spec (machine-readable, includes all schemas)
- `GET /api/docs` — Swagger UI
- `GET /api/mirrors` — Active mirror domains, Tor onion, official channels (Telegram, Reddit, etc.)
- `GET /.well-known/ai-plugin.json` — ChatGPT plugin manifest

## ChatGPT Custom GPT

TorrentClaw is published as a ChatGPT Custom GPT with Actions. The GPT searches torrents, checks streaming availability, browses trending and upcoming content via natural language using the OpenAPI schema.

OpenAPI schema: https://torrentclaw.com/api/openapi.json

## MCP Server

Install the Model Context Protocol server to let Claude / Cursor / Cline / any MCP-aware agent call TorrentClaw via natural language:

```
npx -y @torrentclaw/mcp
```

MCP tools exposed: `search_torrents`, `autocomplete`, `get_stats`, `get_torrent_file` (more on the way: `trending`, `upcoming`, `streaming_top`).

## Public BitTorrent Tracker

Anyone can use TorrentClaw's chihaya tracker for any swarm:

- `udp://tracker.torrentclaw.com:1337/announce`
- `http://tracker.torrentclaw.com:6969/announce`

Health stats published at `/api/v1/tracker-stats` for newtrackon-style aggregators.

## Common LLM Use Cases

- Search a movie/show by name and pick the best torrent (highest `qualityScore`)
- Filter by genre, year range, minimum rating, resolution (480p / 720p / 1080p / 2160p), HDR, audio, language, or subtitles
- Restrict to TrueSpec-verified releases (`verified=true`) when accuracy matters
- Get a magnet link or `.torrent` file URL for a specific title
- Browse trending today, this week or this month
- Discover what's coming in the next 6 months with `/upcoming`
- See the Top 10 on Netflix / Prime / Disney+ / Apple TV+ / Crunchyroll by country with `/streaming-top`
- Check streaming availability per country via `search?country=US`
- Explore collections / sagas (Marvel, LOTR, Mission Impossible…)
- Hand a Torznab URL to Sonarr/Radarr and pre-filter with TrueSpec quality tags
- Add a magnet to the user's debrid account or check if it's already cached
- Subscribe to RSS feeds (popular, recent, custom search)

## Links

- Website: https://torrentclaw.com
- OpenAPI Spec: https://torrentclaw.com/api/openapi.json
- Swagger UI: https://torrentclaw.com/api/docs
- Extended LLM docs: https://torrentclaw.com/llms-full.txt
- AI Plugin manifest: https://torrentclaw.com/.well-known/ai-plugin.json
- MCP Server: https://www.npmjs.com/package/@torrentclaw/mcp
- Status / mirrors: https://torrentclaw.com/api/mirrors