docs: align API docs with OpenAPI spec and improve ClawHub discoverability
This commit is contained in:
Deivid Soto
parent
98c550feb0
commit
1363ebaf76
4 changed files with 132 additions and 36 deletions
14
CHANGELOG.md
14
CHANGELOG.md
|
|
@ -6,12 +6,16 @@ All notable changes to this project will be documented in this file.
|
|||
|
||||
### Features
|
||||
|
||||
- Search movies and TV shows across 12+ torrent sources
|
||||
- Filter by quality (480p-2160p), genre, year, rating, language, season/episode
|
||||
- API key authentication with tiered rate limits
|
||||
- Quality scoring (0-100) based on resolution, codec, seeders, source trust
|
||||
- Search movies and TV shows across 30+ torrent sources
|
||||
- Filter by quality (480p–2160p), genre, year, rating, language, season/episode
|
||||
- HDR and Dolby Vision filtering (hdr10, dolby_vision, hdr10plus, hlg)
|
||||
- Audio codec filtering (AAC, FLAC, Opus, Atmos)
|
||||
- API key authentication with tiered rate limits (anonymous, free, pro)
|
||||
- Quality scoring (0–100) based on resolution, codec, seeders, source trust
|
||||
- Multi-language support (11 languages with accent-insensitive search)
|
||||
- TMDB metadata enrichment: posters, backdrops, genres, cast, director credits
|
||||
- Detect installed torrent clients (Transmission, aria2)
|
||||
- Add magnet links directly to torrent clients
|
||||
- Download .torrent files or copy magnet links
|
||||
- OS-specific installation guides for torrent clients
|
||||
- OS-specific installation guides for torrent clients (Linux, macOS, Windows/WSL)
|
||||
- MCP server alternative for Claude Desktop, Cursor, and Windsurf
|
||||
|
|
|
|||
21
README.md
21
README.md
|
|
@ -4,23 +4,24 @@
|
|||
**License:** MIT
|
||||
**Homepage:** https://torrentclaw.com
|
||||
|
||||
Agent Skill for searching and downloading torrents via [TorrentClaw](https://torrentclaw.com).
|
||||
Search and download movies and TV shows from 30+ torrent sources directly from your AI agent. TorrentClaw aggregates torrents from YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv and more — enriched with TMDB metadata, quality scoring, and multi-language support.
|
||||
|
||||
Compatible with Claude Code, OpenClaw, Codex CLI, Cline, Roo Code, and any tool supporting the [Agent Skills](https://agentskills.io) specification.
|
||||
Compatible with **Claude Code**, **OpenClaw**, **Codex CLI**, **Cline**, **Roo Code**, and any tool supporting the [Agent Skills](https://agentskills.io) specification.
|
||||
|
||||
**Alternative:** For Claude Desktop, Cursor, or Windsurf, use the [MCP Server](https://torrentclaw.com/mcp) instead (`npx @torrentclaw/mcp`).
|
||||
|
||||
## Features
|
||||
|
||||
- Search movies and TV shows across 12+ torrent sources (YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv, and more)
|
||||
- Filter by quality (480p-2160p), genre, year, rating, language, season/episode (S01E05, 1x05)
|
||||
- API key authentication for higher rate limits (120 req/min free, 1K req/min pro)
|
||||
- Quality scoring (0-100) based on resolution, codec, seeders, source trust
|
||||
- Search movies and TV shows across 30+ torrent sources (YTS, EZTV, Knaben, Prowlarr, Bitmagnet, Torrentio, DonTorrent, Torrents.csv, and more)
|
||||
- Filter by quality (480p–2160p), genre, year, rating, language, audio codec, HDR format, season/episode
|
||||
- HDR and Dolby Vision filtering (hdr10, dolby_vision) and audio codec filtering (AAC, FLAC, Opus, Atmos)
|
||||
- Quality scoring (0–100) based on resolution, codec, seeders, source trust
|
||||
- Multi-language support (11 languages with accent-insensitive search)
|
||||
- Detect installed torrent clients (Transmission, aria2)
|
||||
- Add magnet links directly to your torrent client
|
||||
- TMDB metadata enrichment: posters, backdrops, genres, cast, director credits
|
||||
- Detect installed torrent clients (Transmission, aria2) and add magnets directly
|
||||
- Download .torrent files or copy magnet links
|
||||
- OS-specific installation guides for torrent clients
|
||||
- OS-specific installation guides for torrent clients (Linux, macOS, Windows/WSL)
|
||||
- API key authentication for higher rate limits (anonymous 30/min, free 120/min, pro 1K/min)
|
||||
|
||||
## Install
|
||||
|
||||
|
|
@ -64,7 +65,7 @@ Or just ask naturally:
|
|||
|
||||
The skill will:
|
||||
1. Detect your torrent client (Transmission, aria2)
|
||||
2. Search TorrentClaw across 12+ sources
|
||||
2. Search TorrentClaw across 30+ sources
|
||||
3. Present results ranked by quality score (0-100)
|
||||
4. Add best torrent to your client or provide magnet link
|
||||
5. Show install guide if no client detected
|
||||
|
|
|
|||
66
SKILL.md
66
SKILL.md
|
|
@ -2,7 +2,7 @@
|
|||
name: torrentclaw
|
||||
description: Search and download torrents via TorrentClaw. Use when the user asks to find, search, or download movies, TV shows, or torrents. Detects local torrent clients (Transmission, aria2) and adds magnets directly, or offers magnet link copy and .torrent file download. Supports filtering by type (movie/show), genre, year, quality (480p-2160p), rating, language, and season/episode (S01E05, 1x05). Features API key authentication with tiered rate limits, AI-verified matching, and quality scoring (0-100). Returns titles with posters, ratings, and torrents with magnet links and quality scores.
|
||||
license: MIT
|
||||
metadata: {"version": "0.1.13", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"]}}
|
||||
metadata: {"version": "0.1.13", "repository": "https://github.com/torrentclaw/torrentclaw-skill", "homepage": "https://torrentclaw.com", "openclaw": {"emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": {"bins": ["curl", "bash", "jq"], "env": ["TORRENTCLAW_API_KEY"]}, "primaryEnv": "TORRENTCLAW_API_KEY"}, "tags": ["torrent", "movies", "tv-shows", "download", "media", "entertainment", "magnet", "transmission", "aria2", "search", "4k", "hdr"]}
|
||||
---
|
||||
|
||||
# TorrentClaw
|
||||
|
|
@ -44,6 +44,8 @@ curl -s -H "x-search-source: skill" "https://torrentclaw.com/api/v1/search?q=QUE
|
|||
- `year_min=2020&year_max=2025`
|
||||
- `min_rating=7`
|
||||
- `lang=es` (ISO 639 language code)
|
||||
- `audio=atmos` (also: aac, flac, opus)
|
||||
- `hdr=dolby_vision` (also: hdr10, hdr10plus, hlg)
|
||||
- `season=1` — Filter by TV show season
|
||||
- `episode=5` — Filter by episode number
|
||||
- `locale=es` — Get titles in Spanish (also: fr, de, pt, it, ja, ko, zh, ru, ar)
|
||||
|
|
@ -101,13 +103,13 @@ Recommend **Transmission** for Linux/macOS (lightweight daemon, simple CLI) and
|
|||
|
||||
Main search endpoint. Required: `q` (query string).
|
||||
|
||||
**Filters:** `type` (movie/show), `genre`, `year_min`, `year_max`, `min_rating` (0-10), `quality` (480p/720p/1080p/2160p), `lang` (ISO 639), `availability` (all/available/unavailable).
|
||||
**Filters:** `type` (movie/show), `genre`, `year_min`, `year_max`, `min_rating` (0-10), `quality` (480p/720p/1080p/2160p), `lang` (ISO 639), `audio` (aac/flac/opus/atmos), `hdr` (hdr10/dolby_vision/hdr10plus/hlg).
|
||||
|
||||
**Sorting:** `sort` = relevance | seeders | year | rating | added
|
||||
|
||||
**Pagination:** `page` (1-1000), `limit` (1-50, default 20)
|
||||
|
||||
**Response:** `{ total, page, pageSize, results: [{ id, imdbId, tmdbId, contentType, title, year, overview, posterUrl, genres, ratingImdb, ratingTmdb, hasTorrents, maxSeeders, torrents: [{ infoHash, magnetUrl, torrentUrl, quality, codec, sourceType, sizeBytes, seeders, leechers, source, qualityScore, scrapedAt, languages, audioCodec, hdrType }] }] }`
|
||||
**Response:** `{ total, page, pageSize, results: [{ id, imdbId, tmdbId, contentType, title, year, overview, posterUrl, backdropUrl, genres, ratingImdb, ratingTmdb, contentUrl, hasTorrents, maxSeeders, torrents: [{ infoHash, magnetUrl, torrentUrl, quality, codec, sourceType, sizeBytes, seeders, leechers, source, qualityScore, scrapedAt, uploadedAt, languages, audioCodec, hdrType, releaseGroup, isProper, isRepack, isRemastered, season, episode }] }] }`
|
||||
|
||||
**New fields:**
|
||||
- `hasTorrents` (boolean) — Whether content has any associated torrents
|
||||
|
|
@ -120,11 +122,11 @@ Fast typeahead. Param: `q` (min 2 chars). Returns max 8 suggestions.
|
|||
|
||||
### Popular — `GET /api/v1/popular`
|
||||
|
||||
Trending content by seeders. Params: `limit` (1-24), `page`.
|
||||
Trending content by seeders. Params: `limit` (1-24, default 12), `page`.
|
||||
|
||||
### Recent — `GET /api/v1/recent`
|
||||
|
||||
Recently added content. Params: `limit` (1-24), `page`.
|
||||
Recently added content. Params: `limit` (1-24, default 12), `page`.
|
||||
|
||||
### Torrent File — `GET /api/v1/torrent/{infoHash}`
|
||||
|
||||
|
|
@ -134,25 +136,34 @@ Download .torrent file by 40-char hex info hash. Returns binary `application/x-b
|
|||
|
||||
Content/torrent counts and recent ingestion history. No params.
|
||||
|
||||
### Content Details — `GET /api/v1/content/:id`
|
||||
### Credits — `GET /api/v1/content/{id}/credits`
|
||||
|
||||
Full metadata for a specific movie or show. Returns complete content object with all torrents, cast, crew, and metadata.
|
||||
Director and top 10 cast members with character names.
|
||||
|
||||
### Track — `GET /api/v1/track`
|
||||
**Params:** `id` (path, required — content ID from search)
|
||||
|
||||
Analytics tracking endpoint. Params: `contentId` (required), `type` (view/click/download).
|
||||
**Response:** `{ contentId, director: "name", cast: [{ name, character, profileUrl }] }`
|
||||
|
||||
**Usage:** Show cast info when the user asks "who's in this movie?" or wants details about a search result.
|
||||
|
||||
### Track — `POST /api/v1/track`
|
||||
|
||||
Record user interactions for popularity ranking. Call this after the user selects a torrent.
|
||||
|
||||
**Request body (JSON):**
|
||||
```json
|
||||
{"infoHash": "40-char hex", "action": "magnet|torrent_download|copy"}
|
||||
```
|
||||
|
||||
**Response:** `{"ok": true}`
|
||||
|
||||
### Search Analytics — `GET /api/v1/search-analytics`
|
||||
|
||||
Popular searches and trending queries. **Requires API key with pro tier.**
|
||||
Search volume, top queries, and zero-result queries by period. **Requires API key with pro tier.**
|
||||
|
||||
### Cache Stats — `GET /api/v1/cache-stats`
|
||||
**Params:** `days` (1-90, default 7), `limit` (1-100, default 20)
|
||||
|
||||
Search cache metrics and performance stats. No params.
|
||||
|
||||
### Enrichment Stats — `GET /api/v1/enrichment-stats`
|
||||
|
||||
TMDB enrichment progress and coverage statistics. No params.
|
||||
**Response:** `{ period, summary, topQueries, zeroResultQueries, dailyVolume }`
|
||||
|
||||
## Season & Episode Search
|
||||
|
||||
|
|
@ -248,12 +259,29 @@ curl -H "Authorization: Bearer tc_live_xxxxx" \
|
|||
|
||||
**Find popular sci-fi movies:**
|
||||
```bash
|
||||
curl "https://torrentclaw.com/api/v1/search?genre=science-fiction&type=movie&sort=seeders"
|
||||
curl "https://torrentclaw.com/api/v1/search?genre=Science%20Fiction&type=movie&sort=seeders"
|
||||
```
|
||||
|
||||
**Track content view for analytics:**
|
||||
**Find Dolby Vision / HDR content:**
|
||||
```bash
|
||||
curl "https://torrentclaw.com/api/v1/track?contentId=123&type=view"
|
||||
curl "https://torrentclaw.com/api/v1/search?q=dune&hdr=dolby_vision&quality=2160p"
|
||||
```
|
||||
|
||||
**Find Atmos audio torrents:**
|
||||
```bash
|
||||
curl "https://torrentclaw.com/api/v1/search?q=oppenheimer&audio=atmos"
|
||||
```
|
||||
|
||||
**Get cast info for a movie:**
|
||||
```bash
|
||||
curl "https://torrentclaw.com/api/v1/content/42/credits"
|
||||
```
|
||||
|
||||
**Track torrent selection (call after user picks a torrent):**
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" \
|
||||
-d '{"infoHash":"aaf1e71c...","action":"magnet"}' \
|
||||
"https://torrentclaw.com/api/v1/track"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
|
|
|||
|
|
@ -43,6 +43,9 @@
|
|||
"audioCodec": "AAC",
|
||||
"hdrType": null,
|
||||
"releaseGroup": "YTS",
|
||||
"isProper": false,
|
||||
"isRepack": false,
|
||||
"isRemastered": false,
|
||||
"season": null,
|
||||
"episode": null
|
||||
}
|
||||
|
|
@ -81,24 +84,79 @@ X-Api-Key-Id: tc_live_abc1
|
|||
- **Pro**: 1,000 req/min, 10,000 req/day (with API key)
|
||||
- **Internal**: Unlimited (with API key)
|
||||
|
||||
## New Query Parameters
|
||||
## 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)
|
||||
|
||||
## New Response Fields
|
||||
## 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
|
||||
|
||||
|
|
@ -115,8 +173,13 @@ X-Api-Key-Id: tc_live_abc1
|
|||
|----------|-------|
|
||||
| /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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue