# Torrent Aggregator

> Open-source torrent metadata search API — aggregates movies and TV shows from multiple sources into a single, searchable endpoint.

## What It Does

Torrent Aggregator collects torrent metadata from YTS, EZTV, Knaben, Prowlarr, and Bitmagnet, enriches it with TMDB metadata (posters, genres, translations), and exposes it through a fast JSON API. No authentication required.

## API Endpoints

- `GET /api/v1/search?q=...` — Search movies and TV shows with filters (type, genre, year, quality, rating, language, sort, pagination)
- `GET /api/v1/autocomplete?q=...` — Typeahead search suggestions (min 2 chars)
- `GET /api/v1/stats` — Aggregator statistics (content counts, torrent counts by source, recent ingestions)
- `GET /api/v1/torrent/{infoHash}` — Download .torrent file by info hash (40 hex chars)

## Documentation

- Full API docs (Swagger UI): /api/docs
- OpenAPI 3.1 spec: /api/openapi.json
- Extended LLM docs: /llms-full.txt

## MCP Server

Install the MCP server to let AI agents search torrents via natural language:

```
npx torrent-api-mcp
```

MCP tools: `search_torrents`, `get_stats`, `get_torrent_file`, `autocomplete`

Docs: /llms-full.txt#mcp-server

## Common LLM Use Cases

- Search for a movie/show by name and get torrent download options
- Find the highest quality (best qualityScore) torrent for a title
- Filter by genre, year range, minimum rating, or resolution (720p/1080p/2160p)
- Get magnet links or .torrent file URLs for a specific title
- Check aggregator statistics and data source health
- Autocomplete partial title queries for interactive search