.. highlight:: xml Web API ======= .. sectionauthor:: bb at #newznab (irc.synirc.org) .. sectionauthor:: ensi at #newznab (irc.synirc.org) Introduction ------------ This document describes the NEWZNAB Usenet Searching Web API. The API is designed to be implemented by Usenet indexing sites, i.e. sites that index Usenet newsgroups through some means, typically by downloading and inspecting the NTTP headers. The API is aimed for NZB aware client applications to allow them to perform Usenet searches against Newznab servers and receive NZB information in order to facilitate direct downloading from Usenet without having to download any NTTP headers. This document does not describe the actual implementation of either the client or the server but just describes the HTTP(S) interface and request/response sequences. Intended readers are server and client implementers. Notation ~~~~~~~~ This document uses the following notations: Parameters: * ``t=c`` denotes a required HTTP query parameter. * ``[o=json | o=xml]`` denotes optional parameters with possible values. Functions --------- All functions are executed as HTTP(S) requests over TCP. All parameters are to be passed as query parameters unless otherwise indicated. All returned XML/JSON data is UTF-8 encoded unless otherwise specified. All query parameters should be UTF-8 and URL encoded, i.e.:: query-param = URL-ENCODE(UTF8-ENCODE(param=value)). The functions are divided into two categories. Functions specific to searching and retrieving of items and the their information such as SEARCH and TV-SEARCH and functions that are for site/user account management such as CAPS and REGISTER. Any conforming implementation should support the CAPS and SEARCH functions. Other functions are optional and if not supported will return the "203 Function Not Available" when invoked. CAPS ~~~~ The ``CAPS`` function is used to query the server for supported features and the protocol version and other meta data relevant to the implementation. This function doesn't require the client to provide any login information but can be executed out of "login session". **Returned Fields** =========================== =========================================== server/version The version of the protocol implemented by the server. All implementations should be backwards compatible. limits The limit and defaults to the number of search results returned. retention Server retention (how many days NZB information is stored before being purged). searching Describes the level of search support and which search parameters are available. searching/search General search, available (yes/no) and supported parameters. searching/tv-search TV search, available and supported parameters e.g. tvdbid,tvmazeid,season,ep searching/movie-search Movie search, available and supported parameters e.g. q,imdbid,genre category Defines a searchable category which might have any number of subcategories. category/id Unique category ID, can be either one of the standard category IDs or a site specific ID. category/name Any descriptive name for the category. Can be site/language specific. category/description A description of the contents of the category. category/subcat A subcategory. category/subcat/id Unique category ID, can be either one of the standard category IDs or a site specific ID. category/subcat/name Any descriptive name for the category. Can be site/language specific. category/subcat/description A description of the contents of the category. groups Defines a list of active, indexed usenet groups. group/name Name of usenet group. group/description Description of usenet group. group/lastupdate Date and time usenet group was last updated. genres Defines a list of active genres. genre/id Id of genre. genre/name Name of genre. genre/categoryid The category the genre is associate with. =========================== =========================================== **HTTP Method** GET **HTTP Response** 200 OK **Parameters** =============== ===================================== ``t=caps`` Caps function, must always be "caps". =============== ===================================== **Optional parameters** =============== ======================================================= ``o=xxx`` Output format, either "JSON" or "XML. Default is "XML". =============== ======================================================= **Examples** 1) Normal behavior **Request**: ``GET http://servername.com/api?t=caps`` **Response**: ``200 OK`` **Content**:: 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**:: 2) Denial **Request**: ``GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com`` **Response**: ``200 OK`` **Content**:: 3) Registration limit imposed **Request**: ``GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com`` **Response**: ``200 OK`` **Content**:: 4) Registration disabled **Request**: ``GET HTTP://servername.com/api?t=register&email=john.joe%40acme.com`` **Response**: ``200 OK`` **Content**:: 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** ============== =========================================================== ``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**:: 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 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 TV > XviD Some TV show 2) No items matched the search criteria. **Request**: ``GET http://servername.com/api?t=search&apikey=xxxxx&q=linux%20image`` **Response**: ``200 OK`` **Content**:: 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**:: 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**:: 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**:: example.com example.com API results A.Public.Domain.Tv.Show.S06E05 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 TV > XviD Some TV show A.Public.Domain.Tv.Show.S06E05 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 TV > XviD Some TV show 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**:: example.com example.com API results A.Public.Domain.Movie.720p.DTS.x264 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 Movie > XviD Some movie 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**:: example.com example.com API results A.Public.Domain.Album.Name http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 Music > MP3 Some music 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**:: example.com example.com API results A.Public.Domain.Book.Name http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 Book > Ebook Some book 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**:: A.Public.Domain.Tv.Show.S06E05 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/nzb/e9c515e02346086e3a477a5436d7bc8c&i=1&r=18cf9f0a736041465e3bd521d00a90b9 http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c#comments Sun, 06 Jun 2010 17:29:23 +0100 TV > XviD Some TV show 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**:: 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**:: 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**:: 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**:: A.Public.Domain.Tv.Show.S06E05 http://servername.com/details/e9c515e02346086e3a477a5436d7bc8c http://servername.com/nfo/e9c515e02346086e3a477a5436d7bc8c Sun, 06 Jun 2010 17:29:23 +0100 This is the nfo file 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**:: 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**:: 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**:: 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**:: ... 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: 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**:: username_of_poster http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c http://servername.com/rss/viewnzb/e9c515e02346086e3a477a5436d7bc8c Sun, 06 Jun 2010 17:29:23 +0100 Comment about the item 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**:: 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**:: 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**:: 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**:: 2) **Request**: ``GET HTTP://servername.com/api?t=commentadd&apikey=xxxxx&guid=xxxxxxxxx&text=comment`` **Response**: ``200 OK`` **Content**:: 3) **Request**: ``GET HTTP://servername.com/api?t=commentadd&apikey=xxxxx&guid=xxxxxxxxx&text=comment`` **Response**: ``200 OK`` **Content**:: USER ~~~~ The ``USER`` function is used for retrieving information about the user account **HTTP Method** GET **HTTP Response** 200 OK **Parameters** ================= ======================================================= ``t=user`` User function, must always be "user" ================= ======================================================= **Examples** 1) **Request**: ``GET HTTP://servername.com/api?t=user`` **Response**: ``200 OK`` **Content**:: 2) **Request**: ``GET HTTP://servername.com/api?t=user`` **Response**: ``200 OK`` **Content**:: 3) **Request**: ``GET HTTP://servername.com/api?t=user`` **Response**: ``200 OK`` **Content**:: 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** ================= ======================================================= ``t=nzbadd`` NZB add function, must always be "nzbadd" ``apikey=xxxx`` User's key as provided by the service provider. ``cat=xxx`` Optional category for the NZB to be added to. ``includemeta=bool`` Optional whether to import the META NZB head defaults to false. ``dupecheck=bool`` Optional whether to check for duplicates defaults to true. ``file`` POSTed file ``nfo`` POSTed nfo file ``mediainfo`` POSTed mediainfo xml file ================= ======================================================= **Examples** 1) **Request**: ``curl -X POST -F "file=@./The.File.nzb" "nfo=@./Nfo.nfo" "mediainfo=@./Mediainfo.xml" "http://server.com/api?t=nzbadd&apikey=xxx&cat=5030&includemeta=true"`` **Response**: ``200 OK`` **Content**:: 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 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 element:: Newznab Error Codes ------------------- Under normal circumstances i.e. when the HTTP request/response sequence is successfully completed Newznab implementations always respond with ``HTTP 200 OK``. However this doesn't mean that the query was semantically correct. It simply means that the HTTP part of the sequence was successful. One then must check the actual response body/data to see if the request was completed without errors. In case of a Newznab error the response contains an error code and an a description of the error. The error codes have been defined into different ranges. 100-199 Account/user credentials specific error codes, 200-299 API call specific error codes, 300-399 content specific error codes and finally 900-999 Other error codes. ==================== ========================================================== Error code Description ==================== ========================================================== 100 Incorrect user credentials 101 Account suspended 102 Insufficient privileges/not authorized 103 Registration denied 104 Registrations are closed 105 Invalid registration (Email Address Taken) 106 Invalid registration (Email Address Bad Format) 107 Registration Failed (Data error) 200 Missing parameter 201 Incorrect parameter 202 No such function (Function not defined in this specification) 203 Function not available. (Optional function is not implemented) 300 No such item 310 Item already exists 600 Failed to load NZB 601 NZB is duplicate 602 NZB is for a non-existant group 603 NZB failed to write to disk 900 Unknown error 910 API Disabled ==================== ========================================================== Error code example ~~~~~~~~~~~~~~~~~~ 1) Query could not be completed because user credentials are broken **Request**: ``GET http://servername.com/api?t=details&apikey=xxxxx&guid=xxxxxxxxx`` **Response**: ``200 OK`` **Content**::