enki
1b7b70426c
- config: koanf-based loading (defaults → YAML → KINDEXR_ env vars) - db: embedded SQLite migrations with BEGIN/END-aware statement splitter - server: chi router, GET /health returns JSON stats - cmd/kindexr: graceful SIGTERM shutdown - cmd/kindexr-cli: stub - deploy: systemd unit, example config, nginx snippet - all packages covered by race-clean tests
103 lines
3.1 KiB
Markdown
103 lines
3.1 KiB
Markdown
# 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.
|