98c550feb0
Agent Skill for searching and downloading torrents via TorrentClaw. Includes SKILL.md with OpenClaw metadata, bash scripts for torrent client detection, CONTRIBUTING.md, CHANGELOG.md, CI/CD with GitHub Actions (shellcheck + conventional commits), lefthook git hooks, Makefile, and .editorconfig.
165 lines
4.7 KiB
Markdown
165 lines
4.7 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",
|
|
"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 |
|