This is the start of new API documentation aimed at a future release.
The proposed API commands may not be implemented in current or SVN copies of sabnzbd.
|
Table of Contents
|
Overview
Accessing the queue
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 it's web-ui.
Authentication
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.
For /api you add the arguments ma_username and ma_password with the username and password to your request
http://host:port/sabnzbd/api?mode=queue&output=xml&ma_username=USERNAME&ma_password=PASSWORD
Missing or incorrect username and password will return
Missing authentication
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
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 check does not require the API key.
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&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>
<newzbinDetails>True</newzbinDetails>
<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",
"newzbinDetails":true,
"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&output=xml
<?xml version="1.0" encoding="UTF-8" ?>
<history>
<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://newzbin.com/browse/post/0000000/</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&output=json
{
"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://newzbin.com/browse/post/000000/",
"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)
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
Shortest:
URL: api?mode=addurl&name=http://www.example.com/example.nzb
Full:
URL: api?mode=addurl&name=http://www.example.com/example.nzb
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)
Add by newzbin ID
Added in 0.3
Priority added in 0.5
Full:
URL: api?mode=addid&name=333333&pp=3&script=customscript.cmd&cat=Example&priority=-1
Description: pp, script, cat and priority are all optional. This example will retrieve the newzbin post "33333" and instert it at low priority in the queue, assigned with a categoriy of "Example", to execute "customscript.cmd" once finished, and with the unpacking option 3 (Repair, Unpack and Delete)
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:
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
Description:
Config Actions
Set Download Speed limit
Added in 0.4
URL: api?mode=config&name=speedlimit&value=400
Description:
Regenerate new API Key
Added in 0.4.9
URL: api?mode=config&name=set_apikey&apikey=EXISTINGAPIKEY
Description: Returns the new API Key
