# Torznab API

nzbstr implements the [Torznab spec](https://torznab.github.io/spec-1.3-draft/index.html) — a superset of Newznab adapted for BitTorrent. All endpoints are under `/api`.

## Phase availability

| Endpoint | Phase |
|---|---|
| `GET /health` | Phase 0 |
| `GET /api?t=caps` | Phase 1 |
| `GET /api?t=search` | Phase 1 |
| `GET /api?t=tvsearch` | Phase 2 |
| `GET /api?t=movie` | Phase 2 |
| `GET /api?t=music` | Phase 2 |
| `GET /api?t=audio` | Phase 2 |
| `GET /api?t=book` | Phase 2 |

## Authentication

Every endpoint except `/health` requires an `apikey` query parameter.

```
GET /api?t=search&q=breaking+bad&apikey=<your-key>
```

Missing or invalid key returns HTTP 200 with a Torznab error body:

```xml
<error code="100" description="Incorrect user credentials"/>
```

Generate keys with `nzbstr-cli apikey create --label sonarr`.

## `GET /api?t=caps`

Returns a capabilities XML document. Sonarr/Radarr call this on add to discover supported categories and search modes.

Supported search modes:
- `search` — generic FTS5 over title and description
- `tv-search` — `q`, `season`, `ep`, `imdbid`, `tvdbid`, `tmdbid`
- `movie-search` — `q`, `imdbid`, `tmdbid`
- `music-search` — `q`, `artist`, `album`, `year`
- `audio-search` — `q`, `artist`, `album`, `year`
- `book-search` — `q`, `author`, `title`

## `GET /api?t=search`

Parameters: `q`, `cat`, `limit` (default 50, max 100), `offset`, `apikey`.

`q` is passed directly to SQLite FTS5 against the `title` and `description` columns. Supports FTS5 query syntax (`AND`, `OR`, `NOT`, `"phrase"`, `prefix*`).

Returns Torznab RSS XML with `<item>` elements containing:
- `<title>`, `<guid>`, `<link>` (magnet URL), `<pubDate>`, `<size>`, `<description>`
- `<enclosure>` with magnet URL and file size
- `<torznab:attr>` elements for category, infohash, magneturl, seeders, peers, upload/download factors, and ID tags

## `GET /api?t=tvsearch` (Phase 2+)

Additional parameters: `tvdbid`, `imdbid`, `tmdbid`, `season`, `ep`.

Structured ID parameters take priority over `q`. If `season` and/or `ep` are set, results are filtered by the parsed `season` / `episode` columns in the database.

## `GET /api?t=movie` (Phase 2+)

Additional parameters: `imdbid`, `tmdbid`.

## `GET /api?t=music` / `t=audio` (Phase 2+)

Additional parameters: `artist`, `album`, `year`.

## `GET /api?t=book` (Phase 2+)

Additional parameters: `author`, `title`.

## Categories (newznab codes)

| Code | Name |
|---|---|
| 2000 | Movies |
| 2030 | Movies/SD |
| 2040 | Movies/HD |
| 2045 | Movies/UHD |
| 2050 | Movies/BluRay |
| 3000 | Audio |
| 3010 | Audio/MP3 |
| 3030 | Audio/Audiobook |
| 3040 | Audio/Lossless |
| 5000 | TV |
| 5030 | TV/SD |
| 5040 | TV/HD |
| 5045 | TV/UHD |
| 5070 | TV/Anime |
| 7000 | Books |
| 7020 | Books/EBook |
| 7030 | Books/Comics |
| 8000 | Other |

Categories are sourced from NIP-35 `i` tags (`newznab:NNNN` or `tcat:...`) and fall back to `8000` if unknown.

## XML format

nzbstr follows the Torznab RSS 2.0 format. The `xmlns:torznab` namespace is `http://torznab.com/schemas/2015/feed`. All `<torznab:attr>` elements use standard Newznab attribute names so existing *arr configurations work without modification.