Deivid Soto 98c550feb0 feat: initial open-source project structure

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.

2026-02-13 18:40:53 +01:00

4.7 KiB

Raw Blame History

TorrentClaw API Reference

Search Response Schema

{
  "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

# 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

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

# 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

4.7 KiB Raw Blame History