Introduction

Torznab is an api specification based on the Newznab WebAPI. The api is built around a simple xml/rss feed with filtering and paging capabilities.

The Torznab standard strives to be completely compliant with Newznab, insofar it does not conflict with it’s primary goal to supply an consistent api for torrents.

newznab and torznab tags wil be used to designate differences between the two specifications.
The newznab tag either designates newznab specific behavior, or functions that are optional in Newznab and not implemented in Torznab.
The torznab tag indicates functionality specific to Torznab. Some torznab functionality has been implemented later by Newznab, but has not been added to the Newznab WebAPI documentation.

Terminology

This document contains the terms shall, must, should and may. These terms are used in the following meaning:

  • shall and must means that a particular requirement is mandatory. (The chosen term is dependent on the subject type)
  • should means that a particular requirement is recommended but not mandatory.
  • may means that a particular requirement is entirely optional.

Torznab Api Specification

Formatting

The api uses HTTP/HTTPS calls with xml results using the utf-8 encoding.

Standard Queries

Generic

All api calls in torznab consist of a HTTP GET call to the /api endpoint with several query parameters.

t={…} Mandatory. Specifies which function should be invoked.
apikey={…} Authentication key which may be mandatory. Authenticates the user.

The apikey may or may not be mandatory depending on the indexer, most newznab indexers require apikey authentication, but some public indexers do not.

HTTP Request

GET /api?t={function}[&apikey={apikey}]

HTTP Response

200 OK

Function Overview

caps Returns the capabilities of the api.
search Free text search query.
tvsearch Search query with tv specific query params and filtering.
movie Search query with movie specific query params and filtering.
music Search query with music specific query params and filtering.
book Search query with book specific query params and filtering.
details newznab Returns all details about a particular item.
getnfo newznab Returns an nfo for a particular item.
get newznab Returns nzb for the specified item.
card-add newznab Adds item to the users cart.
card-del newznab Removes item from the users cart.
comments newznab Returns all comments known about an item.
comments-add newznab Adds a comment to an item.
register newznab Register a new user account.
user newznab Retrieves information about an user account.

Administrative functions

‘caps’ function

The caps query should be supported by all implementations. It specifies the api version and other metadata useful to the client.

newznab apikey authentication is not required for this function.
torznab apikey authentication is usually not required for this function, but some private trackers require it for security reasons.

HTTP Request

GET /api?t=caps

Response

See Capabilities.

Search functions

Generic

All search functions have certain query params that control the results.

Optional Parameters

cat Comma separated list of category numbers that should be included.
attrs Comma separated list of extended attribute names that should be included in the results.
extended=1 Specifies that all extended attributes should be included in the results. Overrules attrs.
offset Number of items to skip in the result.
limit Number of results to return. Limited by the limits element in the Capabilities.

If offset is out of bounds, then an empty result set will be returned.

Capabilities

The capabilities of the newznab / torznab indexer service is retrievable via the /api?t=caps endpoint. It’s intended to provide the client with information about which search capabilities, categories, groups etc the indexer supports.

This information is crucial since it allows the indexer to implement a limited number of search parameters, clients use the supportedParams list to determine whether efficient ‘indexed’ queries are available or that the client must use the generic q free text search capability.

The result of the api call is a simple XML document with the following format:

Caps Format

Example

<?xml version="1.0" encoding="UTF-8"?>
<caps>
   <server version="1.1" title="..." strapline="..."
         email="..." url="http://indexer.local/"
         image="http://indexer.local/content/banner.jpg" />
   <limits max="100" default="50" />
   <retention days="400" />
   <registration available="yes" open="yes" />

   <searching>
      <search available="yes" supportedParams="q" />
      <tv-search available="yes" supportedParams="q,rid,tvdbid,season,ep" />
      <movie-search available="no" supportedParams="q,imdbid,genre" />
      <audio-search available="no" supportedParams="q" />
      <book-search available="no" supportedParams="q" />
   </searching>

   <categories>
      <category id="2000" name="Movies">
         <subcat id="2010" name="Foreign" />
      </category>
      <category id="5000" name="TV">
         <subcat id="5040" name="HD" />
         <subcat id="5070" name="Anime" />
      </category>
   </categories>

   <groups>
      <group id="1" name="alt.binaries...." description="..." lastupdate="..." />
   </groups>

   <genres>
      <genre id="1" categoryid="5000" name="Kids" />
   </genres>

   <tags>
      <tag name="anonymous" description="Uploader is anonymous" />
      <tag name="trusted" description="Uploader has high reputation" />
      <tag name="internal" description="Uploader is an internal release group" />
   </tags>
</caps>
server Information about the server itself, all attributes are free to be changed by the indexer.
limits Specifies the maximum and default values for the limit query parameter.
retention newznab Usenet retention in days.
torznab Should be omitted.
searching Specifies the search capabilities of individual search modes. See Supported Params.
categories List of known categories for use in the cat query parameter.
groups newznab Optional list of usenet groups that are indexed.
torznab No current application specified.
genres Optional list of known genres for use in the genre query parameter.
tags torznab Optional list of supported tags for use in the tag query parameter.

Supported Params

Extended attributes

Newznab and Torznab use several of the attributes and elements defined by the RSS specification, but also add several additional attributes in a separate xml namespace.

newznab All attributes reside in the xmlns:newznab="http://www.newznab.com/DTD/2010/feeds/attributes/" namespace.
torznab All attributes reside in the xmlns:torznab="http://torznab.com/schemas/2015/feed" namespace.

Extended attributes follow the format:

<torznab:attr name="seeders" value="1" />
<torznab:attr name="category" value="5000" />
<torznab:attr name="category" value="5040" />

Several extended attributes may occur multiple times, such as category.

Clients shall handle attributes with the same name but with different values as a list instead of a singular value. Clients shall ignore duplicate values.

Predefined attributes

These predefined attributes are optional except for the size and category attribute.

Predefined newznab & torznab extended attributes
name scope type description
size all integer Size in bytes
category all integer Category id. May occur multiple times.
tag all string torznab Individual tag. May occur multiple times.
guid all string Unique release guid.
files all integer Number of files in the release
poster all string newznab NNTP poster (eg. yenc@power-poster)
torznab Username that uploaded the release to the tracker.
group all string newznab NNTP Group(s) (eg. a.b.group, a.b.tv)
team all string Team doing the release. (Release Group name)
grabs all integer Number of times the release was fetched from the indexer.
seeders all integer torznab Number of active seeders according to the tracker(s).
leechers all integer torznab Number of active leechers (non-seeders) according to the tracker(s).
peers all integer torznab Number of active peers (seeders and leechers) according to the tracker(s).
infohash all string torznab Torrent infohash as lower-case hexadecimal string.
magneturl all url torznab Magnet uri.
seedtype all string torznab Specifies which seed criteria must be met. Possible values are: ratio, seedtime, both or either (default).
minimumratio all decimal torznab Minimum ratio required before the torrent client may stop seeding.
minimumseedtime all decimal torznab Minimum time in seconds that the torrent must be actively seeded by the client before it may be stopped.
downloadvolumefactor all decimal torznab Multiplier for the download volume that counts toward the user’s account on the tracker. Freeleech would be 0.0.
uploadvolumefactor all decimal torznab Multiplier for the upload volume that counts toward the user’s account on the tracker.
password all integer Whether the archive is passworded (`0`=no, `1`=rar password, `2`=contains inner archive)
comments all integer Number of comments
usenetdate all string newznab Date the release was uploaded to usenet (eg. Tue, 22 Jun 2010 06:54:22 +0100)
nfo all integer Whether an .nfo file is available. (0 no, 1 yes)
info all string Url for the .nfo file.
year all integer Release year
coverurl all string Cover image url
backdropurl all string Backdrop image url
review all string Critics review
season tv integer Season number
episode tv integer Episode number
rageid tv integer Detected TVRage ID. (TVRage.com, now defunct)
tvtitle tv string Human readable Show Title (originally from TV Rage)
tvairdate tv string Air date for the episode (eg. Tue, 22 Jun 2010 06:54:22 +0100)
tvdbid tv integer TheTVDB show id associated with this release.
tvmazeid tv integer TVMaze show id associated with this release.
genre tv, movies string Genre (eg. Horror, Comedy)
video tv, movies string Video Codec (eg. x264)
audio tv, movies, audio string Audio Codec (eg. AC3 2.0 @ 384 kbs)
resolution tv, movies string Video resolution (eg. 1280x716 1.78:1)
framerate tv, movies string Video framerate (eg. 23.976 fps)
language tv, movies, audio string Video/Audio languages (eg. English)
subs tv, movies string Subtitle languages (eg. English, Spanish)
imdb movies string Imdb ID. (www.imdb.com)
imdbscore movies string Imdb score (eg. 5/10)
imdbtitle movies string Imdb title
imdbtagline movies string Imdb tagline
imdbplot movies string Imdb plot
imdbyear movies integer Imdb year
imdbdirector movies string Imdb director
imdbactors movies string Imdb actors
artist music string Artist name
album music string Album name
publisher music string Publisher name
tracks music string Track listing (eg. Track 1|Track 2|Track 3)
booktitle book string Book title
publishdate book string Date the book was published
author book string Booth author
pages book integer Number of book pages

Client Implementation Guidelines

Todo

Needs to be implemented.

Service Implementation Guidelines

These guidelines aim to eliminate ambiguity in the expected behavior of the service implementation. It also describes common pitfalls for service implementations. Service implementations may deviate from these guidelines and as such clients should not assume services to conform.

Parameters

The query parameter’s name must be evaluated case-insensitive.

The service shall verify for each parameter whether the value is within the accepted range or, unless specified, return error 201 - Incorrect parameter.

‘cat’ parameter

The cat parameter is a comma separated list of categories for which the client wishes to receive the results. The service should fully implement this query parameter.

The cat parameter must be verified to contain a comma separated list of integer numbers. For example using the ^d+(,d+)*$ regular expression. If the parameter is invalid, then the error 201 - Incorrect parameter must be returned.

If the cat parameter is not included in the query sent by the client, the service should return the results for all categories.

Unknown categories must be silently ignored, if all categories specified by the cat parameter are unknown then the service shall return an empty result set.

The service shall return an item only once if it exists in multiple specified categories.

Example

cat=4030,5070,1234 returns results that exist in category 4030 and/or 5070. 1234, being an unknown category, is ignored.

cat=1234 returns no results at all since there are no items in the specified unknown category.

‘attrs’ and ‘extended’ parameters

The attrs parameter is a comma separated list of extended attribute names, allowing the client to request that specific extended attributes are included in the results. The extended parameter is used to request all supported extended attributes.

The service shall either implement both parameters, only the extended parameter or none.

If the service does not implement the query parameters, then all supported extended attributes must be included in the result set.

The service shall accept the extended parameter value 1 and 0 to determine whether all extended attributes are requested by the client. The service may also accept the values true/yes and false/no, with any capitalization. Any other value should result in error 201 - Incorrect parameter.

If the extended parameter is not ‘true’ then the service shall include all supported extended attribute specified by the attrs parameter.

The attrs parameter must be validated against invalid characters. For example using the ^[a-zA-Z]+(,[a-zA-Z]+)*$ regular expression. Unknown extended attributes specified in the attrs parameter must be silently ignored.

‘offset’ and ‘limit’ parameters

The offset and limit parameters is used to specify which portion of the result set should be returned to the client. The service shall implement both parameters.

The service shall verify whether both values are integers greater or equal to zero. Otherwise the error 201 - Incorrect parameter must be returned.

The offset specifies how many items in the result set should be skipped. The offset must default to the value zero.

The service shall return an empty result if offset is equal or exceeds the total number of results.

The limit parameter specifies how many results should be returned. The default and maximum value for limit is specified by the Capabilities. The service should automatically limit the value to the maximum.

‘tag’ parameter

Added to torznab in version 1.3.

The service may implement the tag parameter, if it does then the supportedParams attribute in the Capabilities must include ‘tag’.

The tag parameter is a comma separated list of tags that must (not) be present in the results. A prefixed hyphen (-) means exclusion. The order of tags in the list is irrelevant.

Returned results must match all tags specified by the parameter.

The service shall treat unknown tags as if no release has the tag and behave appropriatly based on whether it’s an inclusion or exclusion.

A list of supported tags should be included in the Capabilities.

Example

tag=anonymous,-remake indicates that all releases must have the tag ‘anonymous’ and must not have the tag ‘remake’.

Todo

Incomplete

General api

Todo

Needs to be implemented.