# 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",
          "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)

## New 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`)

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

## New Response Fields

**Content fields:**
- `hasTorrents` (boolean) — Whether content has associated torrents
- `maxSeeders` (number) — Highest seeder count across all torrents for this content

**Torrent fields:**
- `scrapedAt` (string, ISO 8601) — Timestamp of last tracker scrape for real-time seeder/leecher counts

## 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/stats | 10/min |
| /api/v1/torrent | 20/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 |