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 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): Ubuntu ISO x64 Ubuntu ISO x86 (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=&id=[&del=1] 2.11 NZB-ADD Parameters: t=nzbadd apikey=xxxx nzb= Optional: nfo= cat, includemeta, dupecheck, medianfo Legacy fallback: 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: 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.