newznab-tmux/docs/newznab_api_specification.txt

                                    newznab Usenet Searching Web API

                                                v2.0-NNTmux
                                             2026-04-14

Authors:
ensi     ensisoft@gmail.com
newznab  http://newznab.com/
nZEDb    https://github.com/nZEDb/nZEDb
newznab-tmux https://github.com/NNTmux/newznab-tmux

1.  Introduction
2.  Functions
2.1 CAPS
2.2 SEARCH
2.3 TV-SEARCH
2.4 MOVIE-SEARCH
2.5 MUSIC-SEARCH
2.6 BOOK-SEARCH
2.7 ANIME-SEARCH (NNTmux extension)
2.8 DETAILS
2.9 GETNFO
2.10 GET
2.11 NZB-ADD
3.  Unsupported upstream functions
4.  Predefined Categories
5.  Predefined Attributes
6.  Error Codes
7.  Changelog

1. Introduction

   This document describes the newznab-compatible Usenet Searching Web API as
   implemented by NNTmux. It merges upstream newznab additions with
   NNTmux-specific compatibility extensions.

   API endpoints return HTTP 200 on protocol success and report semantic
   errors in the body (`<error code="...">`). Error responses use the HTTP
   status that matches the XML error code (for example 400 for missing or
   incorrect parameters, 401 for invalid credentials, 403 for suspended
   accounts, 404 for missing functions/items, and 429 for request/download
   limits).

1.1 Notation

   Parameters: "t=c" denotes required HTTP query parameter.
   [o=json|o=xml] denotes optional parameters.

2. Functions

   Endpoint:
   GET /api/v1/api

   Optional aliases are supported for several t-values:
   c/caps, s/search, tv/tvsearch, m/movie, b/book, d/details, g/get,
   gn|n|nfo|info/getnfo.

2.1 CAPS

   Parameters:
   t=caps

   Optional:
   o=xml|json

   Returns:
   - server
   - limits
   - registration
   - searching
   - categories
   - groups
   - genres

   searching.supportedParams (NNTmux):
   - search: q,group,minsize,maxsize,maxage,cat,limit,offset,attrs,extended,del,sort
   - tv-search: q,vid,tvdbid,traktid,rid,tvmazeid,imdbid,tmdbid,season,ep,cat,minsize,maxsize,maxage,limit,offset,attrs,extended,del,sort
   - movie-search: q,imdbid,tmdbid,traktid,genre,cat,minsize,maxsize,maxage,limit,offset,attrs,extended,del,sort
   - audio-search: q,cat,minsize,maxsize,maxage,group,limit,offset,attrs,extended,del,sort
   - book-search: q,title,author,cat,minsize,maxsize,maxage,group,limit,offset,attrs,extended,del,sort
   - anime-search: q,anidbid,anilistid,cat,minsize,maxsize,maxage,limit,offset,attrs,extended,del,sort

2.2 SEARCH

   Parameters:
   t=search
   apikey=xxxx

   Optional:
   q=xxxx
   group=xxxx
   limit=123
   cat=xxx
   o=xml|json
   attrs=xxx
   extended=1
   del=1
   maxage=123
   minsize=0
   maxsize=1        (accepted for compatibility, currently not enforced)
   offset=50
   sort=val_asc|val_desc

   sort values:
   cat, name, size, files, stats, posted
   Example: sort=size_desc

   Sorting request examples:
   - /api?v=1&t=search&apikey=xxxx&q=ubuntu&sort=posted_desc
   - /api?v=1&t=search&apikey=xxxx&q=ubuntu&sort=name_asc
   - /api?v=1&t=search&apikey=xxxx&q=ubuntu&sort=size_desc&limit=50&offset=0

   XML sorting response snippet (size_desc):
   <item>
     <title>Ubuntu ISO x64</title>
     <newznab:attr name="size" value="734003200"/>
   </item>
   <item>
     <title>Ubuntu ISO x86</title>
     <newznab:attr name="size" value="367001600"/>
   </item>
   (larger size appears first because sort=size_desc)

   Response additions:
   - newznab:response offset/total
   - newznab:apilimits apicurrent/apimax/grabcurrent/grabmax/apioldesttime/graboldesttime

2.3 TV-SEARCH

   Parameters:
   t=tvsearch
   apikey=xxxx

   Optional:
   q, vid, tvdbid, traktid, rid, tvmazeid, imdbid, tmdbid
   season, ep
   cat, limit, offset, maxage, minsize, maxsize, attrs, extended, del, sort

   Notes:
   - season YYYY + ep MM/DD is treated as daily date-style query.
   - Example:
     /api?v=1&t=tvsearch&apikey=xxxx&q=last+week+tonight&season=2025&ep=11/10&sort=posted_desc

2.4 MOVIE-SEARCH

   Parameters:
   t=movie
   apikey=xxxx

   Optional:
   q, imdbid, tmdbid, traktid, genre
   cat, limit, offset, maxage, minsize, maxsize, attrs, extended, del, sort

   Example:
   /api?v=1&t=movie&apikey=xxxx&imdbid=tt0816692&sort=size_desc

2.5 MUSIC-SEARCH

   Parameters:
   t=music (alias t=audio)
   apikey=xxxx

   Optional:
   q
   album, artist, label, track, year, genre
   group, cat, limit, offset, maxage, minsize, maxsize, attrs, extended, del, sort

2.6 BOOK-SEARCH

   Parameters:
   t=book
   apikey=xxxx

   Optional:
   q
   title, author
   group, cat, limit, offset, maxage, minsize, maxsize, attrs, extended, del, sort

2.7 ANIME-SEARCH (NNTmux extension)

   Parameters:
   t=anime
   apikey=xxxx

   Optional:
   q, anidbid, anilistid
   cat, limit, offset, maxage, minsize, maxsize, attrs, extended, del, sort

2.8 DETAILS

   Parameters:
   t=details
   id=guid
   apikey=xxxx

   Optional:
   o=xml|json
   del=1

2.9 GETNFO

   Parameters:
   t=getnfo (aliases: nfo, info, n, gn)
   id=guid
   apikey=xxxx

   Optional:
   raw=1 or o=file

2.10 GET

   Parameters:
   t=get
   id=guid
   apikey=xxxx

   Optional:
   del=1

   Behavior:
   Redirects to /getnzb?r=<apikey>&id=<guid>[&del=1]

2.11 NZB-ADD

   Parameters:
   t=nzbadd
   apikey=xxxx
   nzb=<multipart nzb file>

   Optional:
   nfo=<multipart nfo file with any basename>
   cat, includemeta, dupecheck, medianfo

   Legacy fallback:
   file=<single multipart nzb or nfo file>

   The legacy file field cannot be mixed with nzb or nfo in the same request.

   Behavior:
   The nzb/nfo fields use the same atomic manifested staging flow as API v2.
   Each pair is isolated below NZB_UPLOAD_FOLDER and the NFO basename does not
   need to match the NZB basename. Run nntmux:import-nzbs first and then
   nntmux:import-nfos for the same folder to link the NFO to the new release.
   Duplicate or failed NZB imports do not link their NFO files.

   Error handling:
   Uses XML error codes from section 6.

3. Unsupported upstream functions

   The following upstream newznab functions are intentionally not implemented
   in NNTmux v1 API:

   - REGISTER (t=register)
   - USER (t=user)
   - COMMENTS (t=comments)
   - COMMENTS-ADD (t=commentadd)
   - CART-ADD (t=cartadd)
   - CART-DEL (t=cartdel)

   Requests to these endpoints return:
   <error code="202" description="No such function (...)"/>

4. Predefined Categories

   Category ranges:
   0000-0999   Reserved
   1000-1999   Console
   2000-2999   Movies
   3000-3999   Audio
   4000-4999   PC
   5000-5999   TV
   6000-6999   XXX
   7000-7999   Books
   8000-8999   Other
   9000-99999  Reserved
   100000-     Custom

   Important category IDs (union of upstream + NNTmux):
   7900 Category Not Determined
   8000 Other, 8010 Other/Misc
   1035 Console/Switch
   1090 Console/XBox One
   1100 Console/PS4
   1110 Console/3DS (NNTmux)
   1120 Console/PS Vita (NNTmux)
   1130 Console/WiiU (NNTmux)
   1999 Console/Other (NNTmux)
   2045 Movies/UHD
   2060 Movies/BluRay (NNTmux)
   2070 Movies/DVD (NNTmux)
   2080 Movies/WEBDL (NNTmux)
   2090 Movies/X265 (NNTmux)
   3050 Audio/Podcast
   3060 Audio/Foreign (NNTmux)
   3999 Audio/Other (NNTmux)
   5010 TV/WEB-DL (NNTmux)
   5045 TV/UHD
   5090 TV/X265 (NNTmux)
   5999 TV/OTHER (NNTmux)
   6041 XXX/HD Clips (NNTmux)
   6042 XXX/SD Clips (NNTmux)
   6999 XXX/Packs (NNTmux)
   7040 Books/Technical (NNTmux)
   7060 Books/Foreign (NNTmux)
   7999 Books/Other (NNTmux)

5. Predefined Attributes

   Standard:
   size, category, guid, files, poster, group, grabs, comments, password,
   usenetdate, info, year, genre, imdb, coverurl, review, etc.

   NNTmux extensions:
   prematch, videos_id, tv_episodes_id, tvdbid, traktid, tvmazeid, imdbid,
   tmdbid, title, firstaired, anidbid.

6. Error Codes

   HTTP status mapping:
   - 100, 102, 910: 401 Unauthorized
   - 101, 103, 104, 105, 106: 403 Forbidden
   - 107, 200, 201, 203, 600, 602, 900: 400 Bad Request
   - 202, 300: 404 Not Found
   - 310, 601: 409 Conflict
   - 500, 501: 429 Too Many Requests
   - 603: 500 Internal Server Error

   100 Incorrect user credentials
   101 Account suspended
   102 Insufficient privileges/not authorized
   103 Registration denied
   104 Registrations are closed
   105 Invalid registration (Email Address Taken)
   106 Invalid registration (Email Address Bad Format)
   107 Registration Failed (Data error)

   200 Missing parameter
   201 Incorrect parameter
   202 No such function
   203 Function not available

   300 No such item
   310 Item already exists

   500 Request limit reached (NNTmux)
   501 Download limit reached (NNTmux)

   600 Failed to load NZB
   601 NZB is duplicate
   602 NZB is for a non-existent group
   603 NZB failed to write to disk

   900 Unknown error
   910 API disabled

7. Changelog

   2026-04-14
     - Merged upstream newznab specification updates into NNTmux spec.
     - Added MUSIC-SEARCH, BOOK-SEARCH, GETNFO, GET, NZB-ADD sections.
     - Added sort, minsize/maxsize, attrs, and apilimits documentation.
     - Added CAPS groups/genres documentation.
     - Preserved NNTmux anime search, extended TV identifiers, categories, and attributes.
     - Documented unsupported upstream functions (register/user/comments/cart).

   2015-10-24 ruhllatio
     - Add new attribute returns.
     - Update supported tv-search methods.
     - Add audio-search capability and make it unavailable with no params.

   2015-05-23 kevinlekiller
     - Fix spelling issues.
     - Fix indentation issues.
     - Add missing categories.
     - Add missing error codes.