Web API — Newznab 0.2.3-dev documentation (2024)

Introduction

This document describes the NEWZNAB Usenet Searching Web API. The API isdesigned to be implemented by Usenet indexing sites, i.e. sites that indexUsenet newsgroups through some means, typically by downloading and inspectingthe NTTP headers. The API is aimed for NZB aware client applications to allowthem to perform Usenet searches against Newznab servers and receive NZBinformation in order to facilitate direct downloading from Usenet withouthaving to download any NTTP headers.

This document does not describe the actual implementation of either the clientor the server but just describes the HTTP(S) interface and request/responsesequences.

Intended readers are server and client implementers.

Notation

This document uses the following notations:

Parameters:

  • t=c denotes a required HTTP query parameter.

  • [o=json | o=xml] denotes optional parameters with possible values.

Functions

All functions are executed as HTTP(S) requests over TCP. All parameters are tobe passed as query parameters unless otherwise indicated. All returned XML/JSONdata is UTF-8 encoded unless otherwise specified. All query parameters shouldbe UTF-8 and URL encoded, i.e.:

query-param = URL-ENCODE(UTF8-ENCODE(param=value)).

The functions are divided into two categories. Functions specific to searchingand retrieving of items and the their information such as SEARCH and TV-SEARCHand functions that are for site/user account management such as CAPS andREGISTER.

Any conforming implementation should support the CAPS and SEARCH functions.Other functions are optional and if not supported will return the “203 FunctionNot Available” when invoked.

CAPS

The CAPS function is used to query the server for supported features andthe protocol version and other meta data relevant to the implementation. Thisfunction doesn’t require the client to provide any login information butcan be executed out of “login session”.

Returned Fields

server/version

The version of the protocol implemented bythe server. All implementations should bebackwards compatible.

limits

The limit and defaults to the number ofsearch results returned.

retention

Server retention (how many days NZBinformation is stored before being purged).

searching

Describes the level of search support andwhich search parameters are available.

searching/search

General search, available (yes/no) andsupported parameters.

searching/tv-search

TV search, available and supportedparameters e.g. tvdbid,tvmazeid,season,ep

searching/movie-search

Movie search, available and supportedparameters e.g. q,imdbid,genre

category

Defines a searchable category which mighthave any number of subcategories.

category/id

Unique category ID, can be either one ofthe standard category IDs or a sitespecific ID.

category/name

Any descriptive name for the category. Canbe site/language specific.

category/description

A description of the contents of thecategory.

category/subcat

A subcategory.

category/subcat/id

Unique category ID, can be either one ofthe standard category IDs or a sitespecific ID.

category/subcat/name

Any descriptive name for the category. Canbe site/language specific.

category/subcat/description

A description of the contents of thecategory.

groups

Defines a list of active, indexed usenetgroups.

group/name

Name of usenet group.

group/description

Description of usenet group.

group/lastupdate

Date and time usenet group was lastupdated.

genres

Defines a list of active genres.

genre/id

Id of genre.

genre/name

Name of genre.

genre/categoryid

The category the genre is associate with.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=caps

Caps function, must always be “caps”.

Optional parameters

o=xxx

Output format, either “JSON” or “XML. Default is “XML”.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=caps

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?> <caps> <!-- server information --> <server version="1.0" title="Newznab" strapline="A great usenet indexer" email="info@newznab.com" url="http://servername.com/" image="http://servername.com/theme/black/images/banner.jpg"/> <!-- limit parameter range --> <limits max="100" default="50"/> <!-- the server NZB retention --> <retention days="400"/> <!-- registration available or not --> <registration available="yes" open="yes" /> <!-- The search functions available at the server Any conforming implementation should at least support the basic search. Other search functions are optional. --> <searching> <search available="yes" supportedParams="q"/> <tv-search available="yes" supportedParams="q,rid,tvdbid,imdbid,tvmazeid,season,ep"/> <movie-search available="yes" supportedParams="q,imdbid,genre"/> </searching> <!-- supported categories --> <categories> <category id="1000" name="Console"> <subcat id="1010" name="NDS"/> <subcat id="1020" name="PSP"/> </category> <category id="2000" name="Movies"> <subcat id="2010" name="Foreign"/> </category> <!-- site specific categories --> <category id="1000001" name="Debian" description="Latest Debian stuff"/> <category id="1000002" name="Mandrake 2010" description="Mandrake 2010"> <subcat id="1000003" name="Mandrake 2010 HD" description="Mandrake HD stuff"/> <subcat id="1000004" name="Mandrake 2010 SD" description="Mandrake SD stuff"/> </category> <!-- etc.. --> </categories> </caps></xml>

REGISTER

The REGISTER function is used for automatically creating and registeringuser account. This is an optional function and may or may not be available ata site. It is also possible that function is available but currentlyregistrations at the site are closed.

The only prerequisite for registering an account is a valid email addressand any server policies. It is at the server administration discretion toallow or deny registrations based on for example the validity of the emailaddress or the the current client host address.

On successful registration a valid username, password and api key arereturned to the caller. On error an appropriate error code is returned.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=register

Register function, must always be “register”

email=xxx

A valid email address to be used for registration.(URL/UTF-8 encoded).

Examples

  1. Normal behavior

    Request:

    GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><register username="user123" password="pass123" apikey="abcabcd11234abc" />
  2. Denial

    Request:

    GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="103" description="Registration denied"/>
  3. Registration limit imposed

    Request:

    GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="104" description="No more registrations allowed"/>
  4. Registration disabled

    Request:

    GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="203" description="Function not available"/>

SEARCH

The SEARCH function searches the index for items matching the searchcriteria. On successful search the response contains a list of found items.Even if search matched nothing an empty response set is created and returned.This function requires passing the user credentials.

Searches that include categories that are not supported by the server arestill executed but the non-supported categories are simply skipped. Thisbasically treats such a search simply as a “no match” but allows the samequery to be ran simultaneously against several servers.

The list of search categories specifies a logical OR condition. I.e. an itemmatching the search input in any of the specified categories is considered amatch and is returned. E.g. a search searching for “linux” in “computer” and“ebook” categories searches for matching items in “computer” and “ebook” butdoes not search for example the “movies” category. Items found in eithergroup are then combined into a single result set. If the input string forsearch is empty all items (within the server/query limits) are returned forthe matching categories.

When performing the query the categories to be searched are concatenated intoa single query parameter by , (comma). For example cat=200,300,400,which is then URL encoded.

The returned XML data stream is RSS 2.0 compliant and also containsadditional information in the extra namespace.

Response-offset field identifies the current subset of all the matches thatare being transmitted in the response. In other words, if a search for“disco” finds more matches than the server is capable of transmitting in asingle response, the response needs to be split into several responses. Thenit is’s the clients responsibility to repeat the same query with sameparameters but specify an increased offset in order to return the next set ofresults.

If offset query parameter is not used response data contains items between 0offset - limit. If offset query parameter is out of bounds an empty resultset is returned.

Attrs parameter provides a comma “,” separated list of additional (extended)attributes that the search should return if they are applicable to thecurrent item. If attrs is not specified a set of default parameters isreturned.

Search responses can return information regarding api usage to assist thirdparty tools in knowing when limits will be hit. These are attributes returnedin a newznab:apilimits xml node as described below.

Important fields of the returned data (RSS)

title

Title of the found item.

guid

A globally unique (GUID) item identifier.

pubdate

The publishing date in RSS date object as specified byRFC822/2822. (not the Usenet date)

category

The category the NZB belongs to. (This is human readablefor RSS. More precise category is found in additional data)

enclosure

The NZB url

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=search

Search function, must always be “search”

apikey=xxxx

User’s key as provided by the service provider.

Optional parameters

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=search&apikey=xxxxx&q=a%20tv%20show

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel><title>example.com</tile><description>example.com API results</description><!-- More RSS content --> <!-- apicurrent is the users current total api hits for a period apimax is the total api hits allowed in a period grabcurrent is the users current total grabs for a period grabmax is the total grabs allowed in a period apioldesttime is the oldest recorded api hit graboldesttime is the oldest recorded grab --><newznab:apilimits apicurrent="123" apimax="500" grabcurrent="69" grabmax="250" apioldesttime="Wed, 17 Jul 2019 23:00:49 +0100" graboldesttime="Thu, 18 Jul 2019 04:44:44 +0100" /><!-- offset is the current offset of the response total is the total number of items found by the query --><newznab:response offset="0" total="2344"/><item> <!-- Standard RSS 2.0 Data --> <title>A.Public.Domain.Tv.Show.S06E05</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>TV > XviD</category> <description>Some TV show</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="2000"/> <newznab:attr name="category" value="2030"/> <newznab:attr name="size" value="4294967295"/></item></channel></rss>
  2. No items matched the search criteria.

    Request:

    GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss><channel> <newznab:response offset="0" total="0"/></channel></rss>
  3. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="100" description="Incorrect user credentials"/>
  4. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: key"/>

TV-SEARCH

The TV-SEARCH function searches the index in the TV category for itemsmatching the search criteria. The criteria includes query string and inaddition information about season and episode. On successful search theresponse contains a list of items that matched the query. Even if the searchmatched nothing an empty but valid response is created and returned. Thisfunction requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additionalinformation in the extra namespace and optionally TV specific information.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=tvsearch

TV-Search function, must always be “tvsearch”.

apikey=xxx

User’s key as provided by the service provider.

Optional parameters

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=tvsearch&apikey=xxxq=The%20Beverly%20Hillbillies&season=S01

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel><title>example.com</title><description>example.com API results</description><!-- More RSS content--><!-- offset is the current offset of the response total is the total number of items found by the query--><newznab:response offset="0" total="1234"/><item> <!-- Standard RSS 2.0 data --> <title>A.Public.Domain.Tv.Show.S06E05</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>TV > XviD</category> <description>Some TV show</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="5030"/> <newznab:attr name="size" value="154653309"/> <newznab:attr name="season" value="3"/> <newznab:attr name="episode" value="2"/></item><item> <!-- Standard RSS 2.0 data --> <title>A.Public.Domain.Tv.Show.S06E05</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>TV > XviD</category> <description>Some TV show</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="5000" /> <newznab:attr name="category" value="5030" /> <newznab:attr name="size" value="4294967295" /> <newznab:attr name="season" value="3"/> <newznab:attr name="episode" value="1"/></item><!-- more items to follow --></channel></rss>

MOVIE-SEARCH

The MOVIE-SEARCH function searches the index for items matching an IMDb ID orsearch query. On successful search the response contains a list of items thatmatched the query. Even if the search matched nothing an empty but validresponse is created and returned. This function requires passing the usercredentials.

The returned XML data stream is RSS 2.0 compliant and also contains additionalinformation in the extra namespace and optionally movie specific information.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=movie

Movie-Search function, must always be “movie”.

apikey=xxx

User’s key as provided by the service provider.

Optional parameters

limit=123

Upper limit for the number of items to be returned,e.g. 123.

imdbid=xxxx

IMDB id of the item being queried e.g. 0058935.

cat=xxx

List of categories to search delimited by “,”

genre=xxx

A genre string i.e. ‘Romance’ would match ‘(Comedy,Drama, Indie, Romance)’

q=xxxx

Search input (URL/UTF-8 encoded). Case insensitive.

o=xml

Output format, either “JSON” or “XML”. Default is“XML”.

attrs=xxx

List of requested extended attributes delimeted by “,”

extended=1

List all extended attributes (attrs ignored)

del=1

Delete the item from a users cart on download.

maxage=123

Only return results which were posted to usenet in thelast x days.

offset=50

The 0 based query offset defining which part of theresponse we want.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=movie&apikey=xxx&imdbid=0019798

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <title>example.com</title> <description>example.com API results</description> <!-- More RSS content --> <!-- offset is the current offset of the response total is the total number of items found by the query --> <newznab:response offset="0" total="1234"/> <item> <!-- Standard RSS 2.0 data --> <title>A.Public.Domain.Movie.720p.DTS.x264</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>Movie > XviD</category> <description>Some movie</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="2000" /> <newznab:attr name="category" value="2030" /> <newznab:attr name="size" value="4294967295" /> </item></channel></rss>

MUSIC-SEARCH

The MUSIC-SEARCH function searches the index for items matching music properties.On successful search the response contains a list of items that matched thequery. Even if the search matched nothing an empty but valid response iscreated and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additionalinformation in the extra namespace and optionally music specific information.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=music

Music-Search function, must always be “music”.

apikey=xxx

User’s key as provided by the service provider.

Optional Parameters

limit=123

Upper limit for the number of items to be returned,e.g. 123.

album=xxxx

Album title (URL/UTF-8 encoded). Case insensitive.

artist=xxxx

Artist name (URL/UTF-8 encoded). Case insensitive.

label=xxxx

Publisher/Label name (URL/UTF-8 encoded). Caseinsensitive.

track=xxxx

Track name (URL/UTF-8 encoded). Case insensitive.

year=xxxx

Four digit year of release.

genre=123

List of music genre id’s to search delimited by “,”.See CAPS for available genres.

cat=xxx

List of categories to search delimited by “,”

o=xml

Output format, either “JSON” or “XML”. Default is“XML”.

attrs=xxx

List of requested extended attributes delimited by “,”

extended=1

List all extended attributes (attrs ignored)

del=1

Delete the item from a users cart on download.

maxage=123

Only return results which were posted to usenet in thelast x days.

offset=50

The 0 based query offset defining which part of theresponse we want.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=music&apikey=xxx&album=Groovy&extended=1

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <title>example.com</title> <description>example.com API results</description> <!-- More RSS content --> <!-- offset is the current offset of the response total is the total number of items found by the query --> <newznab:response offset="0" total="1234"/> <item> <!-- Standard RSS 2.0 data --> <title>A.Public.Domain.Album.Name</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>Music > MP3</category> <description>Some music</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="3000" /> <newznab:attr name="category" value="3010" /> <newznab:attr name="size" value="144967295" /> <newznab:attr name="artist" value="Bob Smith" /> <newznab:attr name="album" value="Groovy Tunes" /> <newznab:attr name="publisher" value="Epic Music" /> <newznab:attr name="year" value="2011" /> <newznab:attr name="tracks" value="track one|track two|track three" /> <newznab:attr name="coverurl" value="http://servername.com/covers/music/12345.jpg" /> <newznab:attr name="review" value="This album is great" /> </item></channel></rss>

BOOK-SEARCH

The BOOK-SEARCH function searches the index for items matching book properties.On successful search the response contains a list of items that matched thequery. Even if the search matched nothing an empty but valid response iscreated and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additionalinformation in the extra namespace and optionally music specific information.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=book

Book-Search function, must always be “book”.

apikey=xxx

User’s key as provided by the service provider.

Optional Parameters

limit=123

Upper limit for the number of items to be returned,e.g. 123.

title=xxxx

Book title (URL/UTF-8 encoded). Case insensitive.

author=xxxx

Author name (URL/UTF-8 encoded). Case insensitive.

o=xml

Output format, either “JSON” or “XML”. Default is“XML”.

attrs=xxx

List of requested extended attributes delimited by “,”

extended=1

List all extended attributes (attrs ignored)

del=1

Delete the item from a users cart on download.

maxage=123

Only return results which were posted to usenet in thelast x days.

offset=50

The 0 based query offset defining which part of theresponse we want.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=book&apikey=xxx&author=Charles%20Dack&extended=1

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <title>example.com</title> <description>example.com API results</description> <!-- More RSS content --> <!-- offset is the current offset of the response total is the total number of items found by the query --> <newznab:response offset="0" total="1234"/> <item> <!-- Standard RSS 2.0 data --> <title>A.Public.Domain.Book.Name</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>Book > Ebook</category> <description>Some book</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes --> <newznab:attr name="category" value="7020" /> <newznab:attr name="size" value="144967295" /> <newznab:attr name="author" value="Charles Dack" /> <newznab:attr name="title" value="Weather and Folk Lore of Peterborough and District" /> <newznab:attr name="review" value="This book is a classic" /> </item></channel></rss>

DETAILS

The DETAILS function returns all information for a particular Usenet (NZB) item.The response contains the generic RSS part + full extra information + fulltype/category specific information.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=details

Details function, must always be “details”.

id=xxxx

The GUID of the item being queried.

apikey=xxxx

User’s key as provided by the service provider.

Optional Parameters

o=xxx

Output format, either “JSON” or “XML”. Default is“XML”.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <item> <!-- Standard RSS 2.0 Data --> <title>A.Public.Domain.Tv.Show.S06E05</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9</link> <comments>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments</comments> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <category>TV > XviD</category> <description>Some TV show</description> <enclosure url="http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> <!-- Additional attributes Details function returns all possible attributes that are 1) known and 2) applicable for the item requested. --> <newznab:attr name="category" value="2000" /> <newznab:attr name="category" value="2030" /> <newznab:attr name="size" value="4294967295" /> <newznab:attr name="files" value="107" /> <newznab:attr name="poster" value="example@example.net (example)" /> <newznab:attr name="grabs" value="1" /> <newznab:attr name="comments" value="0" /> <newznab:attr name="usenetdate" value="Tue, 22 Jun 2010 06:54:22 +0100" /> <newznab:attr name="group" value="alt.binaries.tv" /> </item></channel></rss>
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: key"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>

GETNFO

The GETNFO function returns an nfo file for a particular Usenet (NZB) item.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=getnfo Details function, must always be “getnfo”.id=xxxx The GUID of the item being queried.apikey=xxxx User’s key as provided by the service provider.

Optional parameters

raw=1 If provided returns just the nfo file without the rss containero=xxx Output format, either “JSON” or “XML”. Default is “XML”.

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=getnfo&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <item> <!-- Standard RSS 2.0 Data --> <title>A.Public.Domain.Tv.Show.S06E05</title> <guid isPermaLink="true">http://servername.com/details/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/nfo/e9c515e02346086e3a477a5436d7bc8c</link> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <description>This is the nfo file</description> <enclosure url="http://servername.com/nfo/e9c515e02346086e3a477a5436d7bc8c&ampenclosure=1&amp;i=1&amp;r=18cf9f0a736041465e3bd521d00a90b9" length="154653309" type="application/x-nzb" /> </item></channel></rss>
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=getnfo&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: id"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=getnfo&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=getnfo&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>

GET

The GET function returns an nzb for a guid.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=get Details function, must always be “get”.id=xxxx The GUID of the item being queried.apikey=xxxx User’s key as provided by the service provider.

Optional parameters

del=1 If provided removes the nzb from the users cart (if present)

Examples

  1. Normal behavior

    Request:

    GET http://servername.com/api?t=get&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE nzb PUBLIC "-//newzBin//DTD NZB 1.1//EN" "http://www.newzbin.com/DTD/nzb/nzb-1.1.dtd"><nzb xmlns="http://www.newzbin.com/DTD/2003/nzb">...
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=get&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: id"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=get&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=get&apikey=xxxxx&id=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>

CART-ADD

The CART-ADD function adds an item to the users cart.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=cartadd

Cart add function, must always be “cartadd”.

id=xxxx

The GUID of the item being added to the cart.

apikey=xxxx

User’s key as provided by the service provider.

Optional Parameters

o=xxx

Output format, either “JSON” or “XML”. Default is“XML”.

Examples

  1. Default behavior

    Request:

    GET http://servername.com/api?t=cartadd&id=12344234234234&apikey=xxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><cartadd id="123" />
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=cartadd&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: id"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=cartadd&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=cartadd&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>
  5. Query could not be completed because item already exists

    Request:

    GET http://servername.com/api?t=cartadd&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="310" description="Item already exists"/>

CART-DEL

The CART-DEL function deletes an item from the users cart.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=cartdel

Cart del function, must always be “cartdel”.

id=xxxx

The GUID of the item being delete from the cart.

apikey=xxxx

User’s key as provided by the service provider.

Optional Parameters

o=xxx

Output format, either “JSON” or “XML”. Default is“XML”.

Examples

  1. Default behavior

    Request:

    GET http://servername.com/api?t=cartdel&id=12344234234234&apikey=xxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><cartdel id="123" />
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=cartdel&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: id"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=cartdel&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=cartdel&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>

COMMENTS

The COMMENTS function returns all comments known about a release.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=comments

Comments function, must always be “comments”.

guid=xxxx

The GUID of the item being queried.

apikey=xxxx

User’s key as provided by the service provider.

Optional Parameters

o=xxx

Output format, either “JSON” or “XML”. Default is“XML”.

Examples

  1. Default behavior

    Request:

    GET http://servername.com/api?t=comments&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><rss version="2.0"><channel> <item> <!-- Standard RSS 2.0 Data --> <title>username_of_poster</title> <guid isPermaLink="true">http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</guid> <link>http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c</link> <pubDate>Sun, 06 Jun 2010 17:29:23 +0100</pubDate> <description>Comment about the item</description> </item></channel></rss>
  2. Query could not be completed because it was malformed

    Request:

    GET http://servername.com/api?t=comments&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="200" description="Missing parameter: key"/>
  3. Query could not be completed because no such item was available

    Request:

    GET http://servername.com/api?t=comments&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="300" description="No such GUID"/>
  4. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=comments&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"/><error code="100" description="Incorrect user credentials"/>

COMMENTS-ADD

The COMMENTS-ADD function adds a comment to a release.

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=commentadd

Comments-add function, must always be “commentadd”.

guid=xxxx

The GUID of the item being queried.

apikey=xxxx

User’s key as provided by the service provider.

text=xxxx

The comment being added (URL/UTF-8 encoded).

Optional Parameters

o=xxx

Output format, either “JSON” or “XML”. Default is“XML”.

Examples

  1. Request:

    GET HTTP://servername.com/api?t=commentadd&apikey=xxxxx&guid=xxxxxxxxx&text=comment

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><commentadd id="123" />
  2. Request:

    GET HTTP://servername.com/api?t=commentadd&apikey=xxxxx&guid=xxxxxxxxx&text=comment

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="300" description="No such item"/>
  3. Request:

    GET HTTP://servername.com/api?t=commentadd&apikey=xxxxx&guid=xxxxxxxxx&text=comment

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="203" description="Function not available"/>

USER

The USER function is used for retrieving information about the user account

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=user

User function, must always be “user”

Examples

  1. Request:

    GET HTTP://servername.com/api?t=user

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><user username="user123" grabs="123" role="User" apirequests="100" downloadrequests="100"movieview="1" musicview="1" consoleview="1" createddate="2011-08-23 12:31:47" />
  2. Request:

    GET HTTP://servername.com/api?t=user

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="300" description="No such item"/>
  3. Request:

    GET HTTP://servername.com/api?t=user

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="203" description="Function not available"/>

NZB-ADD

The NZB-ADD function is used for posting nzbs to newznab. The user account must belong to asystem role with the ‘canpost=true’ privilege.

HTTP Method

GET (File POSTed as ‘file’)

HTTP Response

200 OK

Parameters

Examples

  1. Request:

    curl -X POST -F "file=@./The.File.nzb" "nfo=@./Nfo.nfo" "mediainfo=@./Mediainfo.xml" "http://server.com/api?t=nzbadd&apikey=xxx&cat=5030&includemeta=true"

    Response:

    200 OK

    Content:

    <success ID="1234" guid="563f4128ea6fc7c4c863c1fb8671fe13" categoryID="5030" name="The.File" />

Predefined Categories

In order to facilitate operation that does not rely on a particular naturallanguage, e.g. english a set of predefined category IDs have been defined. Itis possible to define custom categories in the custom category range. Eachcategory is given a range for a set of subcategories. It is possible for anitem to belong to several categories at the same time.

Category Ranges

Category List

Categories

Category Name

0000

Reserved

1000

Console

1010

Console/NDS

1020

Console/PSP

1030

Console/Wii

1035

Console/Switch

1040

Console/XBox

1050

Console/XBox 360

1060

Console/Wiiware

1070

Console/XBox 360 DLC

1080

Console/PS3

1090

Console/XBox One

1100

Console/PS4

2000

Movies

2010

Movies/Foreign

2020

Movies/Other

2030

Movies/SD

2040

Movies/HD

2045

Movies/UHD

2050

Movies/BluRay

2060

Movies/3D

3000

Audio

3010

Audio/MP3

3020

Audio/Video

3030

Audio/Audiobook

3040

Audio/Lossless

3050

Audio/Podcast

4000

PC

4010

PC/0day

4020

PC/ISO

4030

PC/Mac

4040

PC/Mobile-Other

4050

PC/Games

4060

PC/Mobile-iOS

4070

PC/Mobile-Android

5000

TV

5020

TV/Foreign

5030

TV/SD

5040

TV/HD

5045

TV/UHD

5050

TV/Other

5060

TV/Sport

5070

TV/Anime

5080

TV/Documentary

6000

XXX

6010

XXX/DVD

6020

XXX/WMV

6030

XXX/XviD

6040

XXX/x264

6050

XXX/Pack

6060

XXX/ImgSet

6070

XXX/Other

7000

Books

7010

Books/Mags

7020

Books/EBook

7030

Books/Comics

8000

Other

8010

Other/Misc

7900

Category Not Determined

100000-

Custom

Predefined Attributes

A set of known attributes for items in different categories has been defined.Its possible that not all attributes are available at all times. Therefore aclient application should not rely on any particular attributes being in thereturned data but should take this list as an optional extra information.However attributes marked with * are always available.

Additionally, not all attributes are applicable to all items. The categoryinformation can be used to check which attributes area available for whichcategory items.

All attributes are defined using XML namespace syntax.e.g. xmlns:newznab=”http://www.newznab.com/DTD/2010/feeds/attributes/”

List of Attributes

Attribute

Category

Description

Example value

size *

ALL

Size in bytes

“252322”

category *

ALL

Item’s category

“5004”

guid

ALL

Unique release guid

“6c6734da3e92a7b0e494e896b58081da”

files

ALL

Number of files

“4”

poster

ALL

NNTP Poster

yenc@power-post

group

ALL

NNTP Group(s)

“a.b.group, a.b.tv”

team

ALL

Team doing the release

“Team”

grabs

ALL

Number of times item downloaded

“1”

password

ALL

Whether the archive is passworded

“0” no, “1” rar pass, “2” contains inner archive

comments

ALL

Number of comments

“2”

usenetdate

ALL

Date posted to usenet

“Tue, 22 Jun 2010 06:54:22 +0100”

nfo

ALL

Has an nfo or not

“1”

info

ALL

Info (.nfo) file URL

http://site/api?t=getnfo&id=492296e74a91412aa09aef655fda75e7&raw=1

year

ALL

Release year

“2009”

season

TV

Numeric season

“1”

episode

TV

Numeric episode within the season

“1”

rageid

TV

TVRage ID. (www.tvrage.com)

“2322”

tvtitle

TV

TVRage Show Title. (www.tvrage.com)

“The Show Title”

tvairdate

TV

TVRage Show Air date. (www.tvrage.com)

“Tue, 22 Jun 2010 06:54:22 +0100”

video

TV, Movies

Video codec

“x264”

audio

TV, Movies, Audio

Audio codec

“AC3 2.0 @ 384 kbs”

resolution

TV, Movies

Video resolution

“1280x716 1.78:1”

framerate

TV, Movies

Video fps

“23.976 fps”

language

TV, Movies, Audio

Natural languages

“English”

subs

TV, Movies

Subtitles

“English, Spanish”

imdb

Movies

IMDb ID (www.imdb.com)

“0104409”

imdbscore

Movies

IMDb score

“5/10”

imdbtitle

Movies

IMDb score

“Bobs Movie”

imdbtagline

Movies

IMDb tagline

“Bobs new adventure”

imdbplot

Movies

IMDb plot

“All about the movie”

imdbyear

Movies

IMDb year

“1971”

imdbdirector

Movies

IMDb director

“Bob Smith”

imdbactors

Movies

IMDb actors

“Bob Smith, Kate Smith”

genre

TV, Movies

Genre

“Horror, Comedy”

artist

Music

Artist name

“Bob Smith”

album

Music

Album name

“Groovy Tunes”

publisher

Music, Book

Publisher name

“Epic Music”

tracks

Music

Track listing

“track one|track two|track three”

coverurl

TV, Movies, Music, Book

URL to cover image

http://servername.com/covers/music/12345.jpg

backdropcoverurl

TV, Movies, Music

URL to backdrop image

http://servername.com/covers/movies/12345-backdrop.jpg

review

Movies, Music, Book

Critics review

“This media is great”

booktitle

Book

Book title

“Weather and Folk Lore of Peterborough and District”

publishdate

Book

Date book published

“Tue, 22 Jun 2010 06:54:22 +0100”

author

Book

Book author

“Charles Dack”

pages

Book

Number of pages

“123”

Attribute Example

Example attribute declarations within <item> element:

<newznab:attr name="category" value="2000" /><newznab:attr name="category" value="2030" /><newznab:attr name="size" value="4294967295" />

Newznab Error Codes

Under normal circ*mstances i.e. when the HTTP request/response sequence issuccessfully completed Newznab implementations always respond withHTTP 200 OK. However this doesn’t mean that the query was semanticallycorrect. It simply means that the HTTP part of the sequence was successful.One then must check the actual response body/data to see if the request wascompleted without errors.

In case of a Newznab error the response contains an error code and an adescription of the error.

The error codes have been defined into different ranges. 100-199 Account/usercredentials specific error codes, 200-299 API call specific error codes,300-399 content specific error codes and finally 900-999 Other error codes.

Error code

Description

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 (Function not defined in thisspecification)

203

Function not available. (Optional function is notimplemented)

300

No such item

310

Item already exists

600

Failed to load NZB

601

NZB is duplicate

602

NZB is for a non-existant group

603

NZB failed to write to disk

900

Unknown error

910

API Disabled

Error code example

  1. Query could not be completed because user credentials are broken

    Request:

    GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx

    Response:

    200 OK

    Content:

    <?xml version="1.0" encoding="UTF-8"?><error code="100" description="Incorrect user credentials"/>
Web API — Newznab 0.2.3-dev documentation (2024)

References

Top Articles
Latest Posts
Article information

Author: Van Hayes

Last Updated:

Views: 5407

Rating: 4.6 / 5 (66 voted)

Reviews: 89% of readers found this page helpful

Author information

Name: Van Hayes

Birthday: 1994-06-07

Address: 2004 Kling Rapid, New Destiny, MT 64658-2367

Phone: +512425013758

Job: National Farming Director

Hobby: Reading, Polo, Genealogy, amateur radio, Scouting, Stand-up comedy, Cryptography

Introduction: My name is Van Hayes, I am a thankful, friendly, smiling, calm, powerful, fine, enthusiastic person who loves writing and wants to share my knowledge and understanding with you.