Newznab 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).
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
            The only currently defined search functions are SEARCH and TV-SEARCH.
            Any conforming implementation should at least support the basic search.
            Other search functions are optional.
       -->
       <searching>
           <search available="yes"/>
           <tv-search available="yes"/>
           <movie-search available="no"/>
       </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"/>
   

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.

Todo

What is this set?

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

q=xxxx	Search input (URL/UTF-8 encoded). Case insensitive.
group=xxxx	List of usenet groups to search delimited by “,”
limit=123	Upper limit for the number of items to be returned.
cat=xxx	List of categories to search delimited by “,”
o=xxx	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.
minsize=0	Only return results which have a size greater than minsize (bytes).
maxsize=1	Only return results which have a size less than maxsize (bytes).
offset=50	The 0 based query offset defining which part of the response we want.
sort=val_asc	The sorting of the data. Available options being cat, name, size, files, stats, posted in the format “value_asc/desc”, e.g. &sort=size_desc

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

limit=123	Upper limit for the number of items to be returned, e.g. 123.
rid=xxxx	TVRage id of the item being queried.
tvmazeid=xxxx	TVMaze id of the item being queried.
tvdbid=xxxx	TVDB id of the item being queried.
cat=xxx	List of categories to search delimited by “,”
season=xxxx	Season string, e.g S13 or 13 for the item being queried.
q=xxxx	Search input (URL/UTF-8 encoded). Case insensitive.
ep=xxx	Episode string, e.g E13 or 13 for the item being queried.
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

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

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

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

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 + 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 a user account

HTTP Method

GET

HTTP Response

200 OK

Parameters

t=user	User function, must always be “user”
username=xxx	A valid username (URL/UTF-8 encoded).

Examples

1. Request:

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

   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&username=user123

   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&username=user123

   Response:

   200 OK

   Content:

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

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 Range	Category Name	Comments
0000-0999	Reserved
1000-1999	Console
2000-2999	Movies
3000-3999	Audio
4000-4999	PC
5000-5999	TV
6000-6999	XXX
7000-7999	Books
8000-8999	Other
9000-99999	Reserved	Reserved for future expansion
100000-	Custom	Site specific category range. Defined in CAPS.

Category List

Categories	Category Name
0000	Reserved
1000	Console
1010	Console/NDS
1020	Console/PSP
1030	Console/Wii
1040	Console/XBox
1050	Console/XBox 360
1060	Console/Wiiware
1070	Console/XBox 360 DLC
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
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
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.
300	Item already exists.
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"/>