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

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

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" />

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"/>
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"/>
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 search criteria. 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 are still executed but the non-supported categories are simply skipped. This basically treats such a search simply as a “no match” but allows the same query to be ran simultaneously against several servers.

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

When performing the query the categories to be searched are concatenated into a 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 contains additional information in the extra namespace.

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

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

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

Search responses can return information regarding api usage to assist third party tools in knowing when limits will be hit. These are attributes returned in 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 by RFC822/2822. (not the Usenet date)
category	The category the NZB belongs to. (This is human readable for 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

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>

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>
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"/>
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 items matching the search criteria. The criteria includes query string and in addition information about season and episode. On successful search the response contains a list of items that matched the query. Even if the search matched nothing an empty but valid response is created and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additional information 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

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 or search query. On successful search the response contains a list of items that matched the query. Even if the search matched nothing an empty but valid response is created and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additional information 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 the last x days.
`offset=50`	The 0 based query offset defining which part of the response we want.

Examples

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 the query. Even if the search matched nothing an empty but valid response is created and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additional information 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). Case insensitive.
`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 the last x days.
`offset=50`	The 0 based query offset defining which part of the response we want.

Examples

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 the query. Even if the search matched nothing an empty but valid response is created and returned. This function requires passing the user credentials.

The returned XML data stream is RSS 2.0 compliant and also contains additional information 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 the last x days.
`offset=50`	The 0 based query offset defining which part of the response we want.

Examples

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 + 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

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>

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"/>
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"/>
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

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>

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"/>
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"/>
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

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">
...

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"/>
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"/>
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

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" />
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"/>
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"/>
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"/>
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

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" />
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"/>
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"/>
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

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>

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"/>
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"/>
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

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" />
```
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"/>
```
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

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" />

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"/>

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

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

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"/>