228 lines
6.8 KiB
Markdown
228 lines
6.8 KiB
Markdown
# TorrentClaw API Reference
|
|
|
|
## Search Response Schema
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```json
|
|
{
|
|
"infoHash": "aaf1e71c0a0e3b1c0f1a2b3c4d5e6f7a8b9c0d1e",
|
|
"action": "magnet"
|
|
}
|
|
```
|
|
|
|
Method: **POST**. Actions: `magnet`, `torrent_download`, `copy`. Response: `{"ok": true}`
|
|
|
|
## Search Analytics Response Schema
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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 |
|