Api

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.


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 &lt;Article: article=, bytes=, partnum=, art_id=;
        </warning>
        <warning>
        2008-12-26 19:54:45,861
        WARNING
        [assembler] &lt;Article: article=, bytes=, partnum=, art_id=; missing
        </warning>
        <warning>
        2008-12-26 20:44:28,336
        WARNING
        [decoder] CRC Error in &lt;Article: article=, bytes=, partnum=, art_id=; (4134546D -&gt; 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

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License