**This is the start of new API documentation for release 0.5.0 and later **
|
Table of Contents
|
Overview
Two API types
Starting in 0.5 there are two ways to access the API for backwards compatibility, and ease of use.
For external applications (the one you most likely want to be using):
http://host:port/sabnzbd/api
For template creators:
http://host:port/sabnzbd/tapi
The reasons for this changed are explained in the authentication section below. You will most likely want to be using 'api' and not 'tapi' unless you are working with the .tmpl files sabnzbd uses for its web-ui.
API Key
As of version 0.4.9 the API now requires the users API Key to be supplied all API requests in order for it to work. The API Key is randomly generated and is static unless the user decides to change the key. The user can see their api key on the general page of the configuration pages.
The API key is specified using &apikey=KEY like so:
http://localhost:8080/api?mode=qstatus&output=xml&apikey=711de66ca57dae90338267d05f70efe9
If the key is missing from the request it will return:
error: API Key Required
And if if the api key is incorrect it will return:
error: API Key Incorrect
The API key can be regenerated by the following command, the new api key is returned:
http://localhost:8080/api?mode=config&name=set_apikey&apikey=EXISTINGAPIKEY
The version and auth functions do not require the API key.
Authentication
The preferred way is to use the API key parameter.
If for some reason the API key is disabled and a UI username/password is set, then you must use the ma_* parameters.
The way authentication works changed with 0.5, however 'api' retains the same authentication as previous versions for backwards compatibility. 'tapi' will use a different authentication method, which will most likely be handled by your browser.
http://host:port/sabnzbd/api?mode=queue&output=xml&ma_username=USERNAME&ma_password=PASSWORD
Missing or incorrect username and password will return "error : Missing authentication".
If you want to find out which type of authentication is needed, use the auth function. It will return either "None", "apikey" or "login".
http://host:port/sabnzbd/api?mode=auth
For /tapi you will most likely rely on your browser to handle the authentication. It will pop-up a user/password dialog when you first access your page. If for some reason you need to set the user/pass yourself use the following:
http://username:password@host:port/sabnzbd/tapi?mode=queue&output=xml
Queue XML/JSON Output
Simple Queue Output - XML
Added in 0.3
URL: api?mode=qstatus&output=xml
Description: Depreciated now by the advanced queue output, this is the old api that just provides limited details on the current queue and state of sabnzbd
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<queue>
<paused>True</paused>
<kbpersec>0.0</kbpersec>
<mbleft>854.697840691</mbleft>
<mb>854.697840691</mb>
<noofslots>1</noofslots>
<diskspace1>21.980682373</diskspace1>
<diskspace2>21.980682373</diskspace2>
<timeleft>0:00:00</timeleft>
<jobs>
<job>
<id>SABnzbd_nzo_zt2syz</id>
<msgid>3066202</msgid>
<filename>Ubuntu 8.04 (Hardy Heron) - Desktop CD x64</filename>
<mbleft>854.697840691</mbleft>
<mb>854.697840691</mb>
<index>0</index>
<unpackopts>3</unpackopts>
<cat>Apps</cat>
<script>snarl.exe</script>
<status>Queued</status>
<percentage>0</percentage>
<bytes>896215643.0</bytes>
</job>
</jobs>
</queue>
Simple Queue Output - JSON
Added in 0.3
URL: api?mode=qstatus&output=json
Description: Depreciated now by the advanced queue output, this is the old api that just provides limited details on the current queue and state of sabnzbd
Example:
{
"timeleft":"0:00:00",
"mb":854.697841,
"noofslots":1,
"paused":true,
"mbleft":854.697841,
"diskspace2":21.980682,
"diskspace1":21.980682,
"kbpersec":0.000000,
"jobs":[
{"msgid":"3066202",
"filename":
"Ubuntu 8.04 (Hardy Heron) - Desktop CD x64",
"mbleft":854.697841,"id":"SABnzbd_nzo_zt2syz",
"mb":854.697841}
]
}
Advanced Queue Output - XML
Added in 0.5
URL: api?mode=queue&start=START&limit=LIMIT&output=xml
Description: A verbose output that as well as reporting items in the queue, will report on finished items being processed (verify/repaired/extracted) and other details such as categories, scripts.
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<queue>
<cache_limit>-1</cache_limit>
<categories>
<category>None</category>
<category>apps</category>
<category>books</category>
<category>consoles</category>
<category>emulation</category>
<category>games</category>
<category>misc</category>
<category>movies</category>
<category>music</category>
<category>pda</category>
<category>resources</category>
<category>tv</category>
</cat_list>
<scripts>
<script>None</script>
</script_list>
<paused>True</paused>
<new_rel_url></new_rel_url>
<restart_req>False</restart_req>
<slots>
<slot>
<status>Queued</status>
<index>0</index>
<eta>unknown</eta>
<timeleft>0:00:00</timeleft>
<avg_age>43d</avg_age>
<script>None</script>
<msgid>4295398</msgid>
<verbosity></verbosity>
<mb>785.89</mb>
<mbleft>785.89</mbleft>
<filename>Ubuntu v.8.10</filename>
<priority>Normal</priority>
<cat>Apps</cat>
<percentage>0</percentage>
<nzo_id>SABnzbd_nzo_wgmb1m</nzo_id>
<unpackopts>3</unpackopts>
<size>785.9 MB</size>
</slot>
</slots>
<helpuri>http://wiki.sabnzbd.org/</helpuri>
<uptime>33m</uptime>
<refresh_rate></refresh_rate>
<isverbose>False</isverbose>
<start>0</start>
<version>trunk</version>
<diskspacetotal2>503.32</diskspacetotal2>
<color_scheme></color_scheme>
<darwin>False</darwin>
<nt>True</nt>
<status>Paused</status>
<last_warning></last_warning>
<have_warnings>0</have_warnings>
<cache_art>0</cache_art>
<finishaction>None</finishaction>
<noofslots>1</noofslots>
<cache_size>0</cache_size>
<finish>0</finish>
<new_release></new_release>
<pause_int>0</pause_int>
<mbleft>785.89</mbleft>
<diskspace2>25.08</diskspace2>
<diskspace1>25.08</diskspace1>
<diskspacetotal1>503.32</diskspacetotal1>
<timeleft>0:00:00</timeleft>
<mb>785.89</mb>
<eta>unknown</eta>
<nzb_quota></nzb_quota>
<loadavg></loadavg>
<limit>0</limit>
<kbpersec>0.00</kbpersec>
<speedlimit>0</speedlimit>
<webdir>path\to\templates</webdir>
<queue_details>0</queue_details>
</queue>
Advanced Queue Output - JSON
{
"cache_limit":"-1",
"categories":[
"None",
"apps",
"books",
"consoles",
"emulation",
"games",
"misc",
"movies",
"music",
"pda",
"resources",
"tv"
],
"scripts":[
"None"
],
"paused":true,
"new_rel_url":"",
"restart_req":false,
"slots":[
{
"status":"Queued",
"index":0,
"eta":"unknown",
"timeleft":"0:00:00",
"avg_age":"43d",
"script":"None",
"msgid":"4295398",
"verbosity":"",
"mb":"785.89",
"filename":"Ubuntu v.8.10",
"priority":"Normal",
"cat":"Apps",
"mbleft":"785.89",
"percentage":"0",
"nzo_id":"SABnzbd_nzo_wgmb1m",
"unpackopts":"3",
"size":"785.9 MB"
}],
"helpuri":"http://wiki.sabnzbd.org/",
"uptime":"6m",
"refresh_rate":"",
"isverbose":false,
"start":0,
"version":"trunk",
"diskspacetotal2":"503.32",
"color_scheme":"",
"darwin":false,
"nt":true,
"status":"Paused",
"last_warning":"",
"have_warnings":"0",
"cache_art":"0",
"finishaction":null,
"noofslots":1,
"cache_size":"0",
"finish":0,
"new_release":"",
"pause_int":"0"
,"mbleft":"785.89",
"diskspace2":"25.08",
"diskspace1":"25.08",
"diskspacetotal1":"503.32",
"timeleft":"0:00:00",
"mb":"785.89",
"eta":"unknown",
"nzb_quota":"",
"loadavg":"",
"limit":0,
"kbpersec":"0.00",
"speedlimit":"0",
"webdir":"path\\to\\templates",
"queue_details":"0"
}
History XML/JSON Output
History Output - XML
Added in 0.5
URL: api?mode=history&start=START&limit=LIMIT&output=xml
<?xml version="1.0" encoding="UTF-8" ?>
<history>
<total_size>40.23 GB</total_size> **Since 0.5.2
<month_size>20.12 GB</month_size> **Since 0.5.2
<week_size> 5.15 GB</week_size> **Since 0.5.2
<cache_limit>-1</cache_limit>
<paused>True</paused>
<new_rel_url></new_rel_url>
<restart_req>False</restart_req>
<slots>
<slot>
<action_line></action_line>
<show_details>True</show_details>
<script_log></script_log>
<meta>None</meta>
<fail_message></fail_message>
<loaded>False</loaded>
<id>605</id>
<size>778.1 MB</size>
<category>Movies</category>
<pp>D</pp>
<completeness>0</completeness>
<script></script>
<nzb_name>Ubuntu.nzb</nzb_name>
<download_time>567</download_time>
<storage>X:\Apps\Ubuntu</storage>
<status>Completed</status>
<script_line></script_line>
<completed>1236646078</completed>
<nzo_id>SABnzbd_nzo_ipet0h</nzo_id>
<downloaded>815878352</downloaded>
<report>00000000</report>
<path>\Ubuntu</path>
<postproc_time>368</postproc_time>
<name>Ubuntu</name>
<url>https://nzbmatrix.com/blabla/</url>
<bytes>815878352</bytes>
<url_info>http://www.google.com</url_info>
<stage_log>
<slot>
<name>download</name>
<actions>
<item>Downloaded in 9 minutes 27 seconds at an average of 1404kB/s</item>
</actions>
</slot>
<slot>
<name>repair</name>
<actions>
<item>[Ubuntu] Repaired in 4 minutes 24 seconds</item>
<item>[Ubuntu.sample] Quick Check OK</item>
</actions>
</slot>
<slot>
<name>unpack</name>
<actions>
<item>[Ubuntu] Unpacked 1 file/folder in 36 seconds</item>
</actions>
</slot>
</stage_log>
</slot>
</slots>
<helpuri>http://wiki.sabnzbd.org/</helpuri>
<uptime>12m</uptime>
<version>trunk</version>
<diskspacetotal2>503.32</diskspacetotal2>
<color_scheme></color_scheme>
<darwin>False</darwin>
<nt>True</nt>
<status>Paused</status>
<last_warning></last_warning>
<have_warnings>0</have_warnings>
<cache_art>0</cache_art>
<finishaction>None</finishaction>
<noofslots>516</noofslots>
<cache_size>0</cache_size>
<new_release></new_release>
<pause_int>0</pause_int>
<mbleft>785.89</mbleft>
<diskspace2>25.08</diskspace2>
<diskspace1>25.08</diskspace1>
<diskspacetotal1>503.32</diskspacetotal1>
<timeleft>0:00:00</timeleft>
<mb>785.89</mb>
<eta>unknown</eta>
<nzb_quota></nzb_quota>
<loadavg></loadavg>
<kbpersec>0.00</kbpersec>
<speedlimit>0</speedlimit>
<webdir>path\to\templates</webdir>
</history>
History Output - JSON
Added in 0.5
URL: api?mode=history&start=START&limit=LIMIT&output=json
{
"total_size": 40.30 GB, **Since 0.5.2
"month_size": 20.23 GB, **Since 0.5.2
"week_size": 5.12 GB, **Since 0.5.2
"cache_limit":"-1",
"paused":true,
"new_rel_url":"",
"restart_req":false,
"slots":[
{
"action_line":"",
"show_details":"True",
"script_log":"",
"meta":null,
"fail_message":"",
"loaded":false,
"id":605,
"size":"778.1 MB",
"category":"Apps",
"pp":"D",
"completeness":0,
"script":"",
"nzb_name":"Ubuntu.nzb",
"download_time":567,
"storage":"X:\\Apps\\Ubuntu",
"status":"Completed",
"script_line":"",
"completed":1236646078,
"nzo_id":"SABnzbd_nzo_ipet0h",
"downloaded":815878352,
"report":"000000",
"path":"Ubuntu",
"postproc_time":368,
"name":"Ubuntu",
"url":"https://nzbmatrix.com/blabla/",
"bytes":815878352,
"url_info":"http://google.com",
"stage_log":[
{"name":"download","actions":["Downloaded in 9 minutes 27 seconds at an average of 1404kB/s"]},
{"name":"repair","actions":["[ubuntu] Repaired in 4 minutes 24 seconds","[ubuntu.sample] Quick Check OK"]},
{"name":"unpack","actions":["[ubuntu] Unpacked 1 file/folder in 36 seconds"]}
]
}],
"helpuri":"http://wiki.sabnzbd.org/",
"uptime":"12m",
"version":"trunk",
"diskspacetotal2":"503.32",
"color_scheme":"",
"darwin":false,
"nt":true,
"status":"Paused",
"last_warning":"",
"have_warnings":"0",
"cache_art":"0",
"finishaction":null,
"noofslots":516,
"cache_size":"0",
"new_release":"",
"pause_int":"0",
"mbleft":"785.89",
"diskspace2":"25.08",
"diskspace1":"25.08",
"diskspacetotal1":"503.32",
"timeleft":"0:00:00",
"mb":"785.89",
"eta":"unknown",
"nzb_quota":"",
"loadavg":"",
"kbpersec":"0.00",
"speedlimit":"0",
"webdir":"path\\to\\templates"
}
Other output
Return Version - XML
Added in 0.4
URL: api?mode=version&output=xml
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<versions>
<version>0.4.6</version>
</versions>
Return Version - JSON
Added in 0.4
URL: api?mode=version&output=json
Example:
<?xml version="1.0" encoding="UTF-8" ?>
{"version":"0.4.6"}
Return Warning Data - XML
Added in 0.4
URL: api?mode=warnings&output=xml
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<warnings>
<warning>
2008-12-26 19:53:42,567
WARNING
[decoder] Badly formed yEnc article in <Article: article=, bytes=, partnum=, art_id=;
</warning>
<warning>
2008-12-26 19:54:45,861
WARNING
[assembler] <Article: article=, bytes=, partnum=, art_id=; missing
</warning>
<warning>
2008-12-26 20:44:28,336
WARNING
[decoder] CRC Error in <Article: article=, bytes=, partnum=, art_id=; (4134546D -> A8F07173)
</warning>
<warning>
2008-12-27 01:13:37,349
WARNING
[downloader] Thread 3@news.powerusenet.com:119: timed out
</warning>
<warning>2008-12-27 01:13:38,365
WARNING
[downloader] Thread 2@news.powerusenet.com:119: timed out
</warning>
<warning>2008-12-27 01:45:34,041
WARNING
[downloader] Thread 1@news.powerusenet.com:119: timed out
</warning>
</warnings>
The version check does not require the API key.
Return Warning Data - JSON
Added in 0.4
URL: api?mode=warnings&output=json
Example:
{
"warnings":[
"2008-12-26 19:53:42,567\nWARNING\n[decoder] Badly formed yEnc article in <Article: article=, bytes=, partnum=, art_id=>",
"2008-12-26 19:54:45,861\nWARNING\n[assembler] <Article: article=, bytes=, partnum=, art_id=> missing",
"2008-12-26 20:44:28,336\nWARNING\n[decoder] CRC Error in <Article: article=, bytes=, partnum=, art_id=> (4134546D -> A8F07173)",
"2008-12-27 01:13:37,349\nWARNING\n[downloader] Thread 3@news.powerusenet.com:119: timed out",
"2008-12-27 01:13:38,365\nWARNING\n[downloader] Thread 2@news.powerusenet.com:119: timed out",
"2008-12-27 01:45:34,041\nWARNING\n[downloader] Thread 1@news.powerusenet.com:119: timed out"
]
}
Return Categories - XML
Added in 0.4
URL: api?mode=get_cats&output=xml
Description:
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<categories>
<category>
None
</category>
<category>
Video
</category>
</categories>
Return Categories - JSON
Added in 0.4
URL: api?mode=get_cats&output=json
Description:
Example:
{"categories":["None","Video"]}
Return Scripts - XML
Added in 0.4
URL: api?mode=get_scripts&output=xml
Description:
Example:
<?xml version="1.0" encoding="UTF-8" ?>
<scripts>
<script>
None
</script>
<script>
examplescript.cmd
</script>
</scripts>
Return Scripts - JSON
Added in 0.4
URL: api?mode=get_scripts&output=json
Description:
Example:
{"scripts":["None","examplescript.cmd"]}
Restart SABnzbd
Added in 0.5
URL: api?mode=restart
Description: Restarts sabnzbd and the webserver, will return "ok\n" when restarting STARTS, not when it has completed restarting.
Example Response:
ok\n
Queue Actions
Delete
Deleting a single item:
URL: api?mode=queue&name=delete&value=SABnzbd_nzo_zt2syz
Deleting multiple items:
URL: api?mode=queue&name=delete&value=SABnzbd_nzo_zt2syz,SABnzbd_nzo_df2hyd,SABnzbd_nzo_op3shf
Deleting all items:
URL: api?mode=queue&name=delete&value=all
Description:
Move
Swapping two items
URL: api?mode=switch&value=SABnzbd_nzo_zt2syz&value2=SABnzbd_nzo_df2hyd
Description: "value" is the item you want to move, "value2" is the name of the item where you want to put value one above, shifting value2 down.
0.5 - Will return the new position and priority (space separated, can be -1 if error occurs)
Moving to a specific location in the queue.
URL: api?mode=switch&value=SABnzbd_nzo_zt2syz&value2=0
Description: "value2" is the position in the queue where you wish to move the object. 0 is the top of the queue, 1 is the second item, ect..
Pause
Added in 0.3
URL: api?mode=pause
Description: Pauses the whole queue (do not confuse this will pausing an individual download, this is a global pause)
Temporary Pause
//Added in 0.5/
URL: [http://localhost:8080/sabnzbd/api?mode=config&name=set_pause&value=60&apikey=00000
api?mode=config&name=set_pause&value=60&apikey=00000]
Description: Pauses for a set amount of time (value is the time in minutes to pause the queue)
Resume
Added in 0.3
URL: api?mode=resume
Description: Resumes the whole queue (do not confuse this will resuming an individual download, this is a global resume)
Shutdown
Added in 0.3
URL: api?mode=shutdown
Description: Shuts down SABnzbd.
Add by URL
Added in 0.3
Priority added in 0.5
Shortest:
URL: api?mode=addurl&name=http://www.example.com/example.nzb&nzbname=NiceName
Full:
URL: api?mode=addurl&name=http://www.example.com/example.nzb&pp=3&script=customscript.cmd&cat=Example&priority=-1&nzbname=NiceName
Description: pp, script, cat and priority are all optional. This example adds the nzb into the queue marked as low priority, assigned with a categoriy of "Example", to execute "customscript.cmd" once finished, and with the unpacking option 3 (Repair, Unpack and Delete)
Allows full nzbmatrix links (no need to parse out the ID).
Add by fileupload
Added in 0.3
Priority added in 0.5
Allows a file upload to be sent, will be explained in more depth shortly.
Add by file path
Added in 0.3
Priority added in 0.5
Allows uploading of nzb/rar/zip/gz files by simply providing a local path (has to be accessable by the machine running SABnzbd
URL: api?mode=addlocalfile&name=full/local/path/to/file.ext&pp=1&script=script.cmd&priority=-1
Change Script
Added in 0.4
URL: api?mode=change_script&value=SABnzbd_nzo_zt2syz&value2=examplescript.cmd
Description:
Change Category
Added in 0.4
URL: api?mode=change_cat&value=SABnzbd_nzo_zt2syz&value2=Example
Description:
Action on queue complete
Added in 0.4
URL: api?mode=queue&name=change_complete_action&value=hybernate_pc
Description: (For a script, append script_ to "value" such as "value=script_examplescript.cmd")
Change Post Processing
Added in 0.5
URL: api?mode=change_opts&value=SABnzbd_nzo_zt2syz&value2=0
Description: Change value2 to control what post-processing option to use
Skip: 0
+Repair: 1
+Repair/Unpack: 2
+Repair/Unpack/Delete: 3
Change Priority
Added in 0.5
URL: api?mode=queue&name=priority&value=SABnzbd_nzo_zt2syz&value2=0
Description:
Default Priority: -100
Paused: -2
Low Priority: -1
Normal Priority: 0
High Priority: 1
Will return the new position in the queue if successful.
Pause individual download
Added in 0.5
URL: api?mode=queue&name=pause&value=SABnzbd_nzo_zt2syz
Description:
Resume individual download
Added in 0.5
URL: api?mode=queue&name=resume&value=SABnzbd_nzo_zt2syz
Description:
Retrieve Contents of Queue item
Added in 0.5
URL: api?mode=get_files&output=xml&value=SABnzbd_nzo_zt2syz
Description:
Change item name
Added in 0.5
URL: api?mode=queue&name=rename&value=SABnzbd_nzo_zt2syz&value2=THENEWNAME
Description: Changes the name of an item in the queue. The name is used for the final foldername, and input for any post-processing sorting, if used.
History Actions
Delete
Added in 0.3
Deleting a single item:
URL: api?mode=history&name=delete&value=SABnzbd_nzo_zt2syz
Deleting multiple items:
URL: api?mode=history&name=delete&value=SABnzbd_nzo_zt2syz,SABnzbd_nzo_df2hyd,SABnzbd_nzo_op3shf
Deleting all items:
URL: api?mode=history&name=delete&value=all
Deleting all failed items:
URL: api?mode=history&name=delete&value=failed
Extra parameters:
failed_only, when 1, delete only failed jobs
del_files when 1, all files will be deleted too (only for failed jobs).
Description:
Retry
Added in 0.6.0
Retry a single item, optionally with an new NZB file:
URL: api?mode=retry&value=SABnzbd_nzo_zt2syz
You can optionally upload a file, like "Add by file upload".
Config Actions
Set Download Speed limit
Added in 0.4
URL: api?mode=config&name=speedlimit&value=400
Description:
Set Cleanup List
URL: [http://localhost:8080/sabnzbd/api?mode=set_config&apikey=APIKEY§ion=misc&keyword=cleanup_list&value=.sfv,.nzb,.nfo,.ext]
Description: Creates a new extension cleanup list, and returns it in JSON. Multiple values should be comma-delimited, with no trailing characters.
Example response:
{'misc': {'cleanup_list': ['.sfv', '.nzb', '.nfo', '.ext']}}
Regenerate new API Key
Added in 0.4.9
URL: api?mode=config&name=set_apikey&apikey=EXISTINGAPIKEY
Description: Returns the new API Key
Set/get any configuration item
All keywords in the sabnzbd.ini file can be set through the API.
For readability the apikey and output parameters are omitted.
General form for individual settings.
http://localhost:8080/sabnzbd/api?mode=set_config§ion=SECTION&keyword=KEYWORD&value=VALUE
Examples:
http://localhost:8080/sabnzbd/api?mode=set_config§ion=misc&keyword=dirscan_speed&value=5
Setting a number of values in an RSS feed.
http://localhost:8080/sabnzbd/api?mode=set_config§ion=rss&keyword=MyFeed&enable=1&pp=3
SABnzbd will return all the new settings for that feed as a result.
Read configuration
You can read any subsection of the configuration.
Note that you will never receive passwords, each character will be replaced by a * character.
You can set new passwords through the set_config call.
All values
http://localhost:8080/sabnzbd/api?mode=get_config
All elements in [misc]
http://localhost:8080/sabnzbd/api?mode=get_config§ion=misc
All elements of a server
http://localhost:8080/sabnzbd/api?mode=get_config§ion=servers&keyword=ServerName
