Web API

Introduction

This document describes the NEWZNAB Usenet Searching Web API. The API is designed to be implemented by Usenet indexing sites, i.e. sites that index Usenet newsgroups through some means, typically by downloading and inspecting the NTTP headers. The API is aimed for NZB aware client applications to allow them to perform Usenet searches against Newznab servers and receive NZB information in order to facilitate direct downloading from Usenet without having to download any NTTP headers.

This document does not describe the actual implementation of either the client or the server but just describes the HTTP(S) interface and request/response sequences.

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 to be passed as query parameters unless otherwise indicated. All returned XML/JSON data is UTF-8 encoded unless otherwise specified. All query parameters should be 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 searching and retrieving of items and the their information such as SEARCH and TV-SEARCH and functions that are for site/user account management such as CAPS and REGISTER.

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

CAPS

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

Returned Fields

server/version The version of the protocol implemented by the server. All implementations should be backwards compatible.
limits The limit and defaults to the number of search results returned.
retention Server retention (how many days NZB information is stored before being purged).
searching Describes the level of search support and which search parameters are available.
searching/search General search, available (yes/no) and supported parameters.
searching/tv-search TV search, available and supported parameters e.g. tvdbid,tvmazeid,season,ep
searching/movie-search Movie search, available and supported parameters e.g. q,imdbid,genre
category Defines a searchable category which might have any number of subcategories.
category/id Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/name Any descriptive name for the category. Can be site/language specific.
category/description A description of the contents of the category.
category/subcat A subcategory.
category/subcat/id Unique category ID, can be either one of the standard category IDs or a site specific ID.
category/subcat/name Any descriptive name for the category. Can be site/language specific.
category/subcat/description A description of the contents of the category.
groups Defines a list of active, indexed usenet groups.
group/name Name of usenet group.
group/description Description of usenet group.
group/lastupdate Date and time usenet group was last updated.
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 registering user account. This is an optional function and may or may not be available at a site. It is also possible that function is available but currently registrations at the site are closed.

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

On successful registration a valid username, password and api key are returned 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"/>

DETAILS

The DETAILS function returns all information for a particular Usenet (NZB) item. The response contains the generic RSS part + full extra information + full type/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 container o=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 a system 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 natural language, e.g. english a set of predefined category IDs have been defined. It is possible to define custom categories in the custom category range. Each category is given a range for a set of subcategories. It is possible for an item 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 a client application should not rely on any particular attributes being in the returned 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 category information can be used to check which attributes area available for which category 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 circumstances i.e. when the HTTP request/response sequence is successfully completed Newznab implementations always respond with HTTP 200 OK. However this doesn’t mean that the query was semantically correct. 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 was completed without errors.

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

The error codes have been defined into different ranges. 100-199 Account/user credentials 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 this specification)
203 Function not available. (Optional function is not implemented)
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"/>