API reference
Status of this document
The document describes methods available in NZBGet version 13.0 and later. The document is updated after a new stable version is out. Current testing version may have methods or fields not described here; these methods or fields may change before getting stable.
Protocols
NZBGet supports XML-RPC, JSON-RPC and JSON-P-RPC. RPC-protocols allow to control the program from other applications. Many programming languages have libraries, which make the usage of XML-RPC, JSON-RPC and JSON-P-RPC very simple. The implementations of all three protocols in NZBGet are equal: all methods are identical. You may choose the protocol, which is better supported by your programming language.
Authentication
NZBGet has three pairs of username/password:
- options
ControlUsernameandControlPassword- Full access, usually used when connecting to web-interface; - options
RestrictedUsernameandRestrictedPassword-v15.0Restricted user can control the program with few restrictions. He has access to web-interface and can see most program settings. He can not change program settings and can not view security related options or options provided by extension scripts. In terms of RPC-API see Restricted user. - options
AddUsernameandAddPassword-v15.0This user has only two permissions:- add new downloads using RPC-methods
appendandappendurl; - check program version using RPC-method
version.
- add new downloads using RPC-methods
HTTP basic authentication
The RPC server uses HTTP basic authentication by default. The URL would be something like:
- for XML-RPC:
http://username:password@localhost:6789/xmlrpc - for JSON-RPC:
http://username:password@localhost:6789/jsonrpc - for JSON-P-RPC:
http://username:password@localhost:6789/jsonprp
If HTTP basic authentication is somewhat problematic the username/password can also be passed in the URL as the first part of the path:
http://localhost:6789/username:password/xmlrpc
It is also possible to send the credentials in the header X-Authorization: Basic <base64(username:password)> (used by the web-interface) or in the standard Authorization: Basic ... header.
With the option FormAuth enabled (the default) the web-interface shows its own login form instead of the browser’s built-in dialog. This does not affect RPC clients: the server still replies to non-web-interface requests with HTTP 401 and the WWW-Authenticate: Basic realm="NZBGet" challenge, so tools that do not send credentials preemptively (curl, wget, Sonarr/Radarr and other integrations) keep working as before. Only requests marked as coming from the web-interface (header X-NZBGet-Client: nzbget-webui) receive the 401 response without the challenge, which prevents the browser from popping up its own dialog. With FormAuth=no the web-interface falls back to the browser’s built-in dialog. The web-interface ends the session with POST /logout, which expires the session cookies.
Restricted user
For scripts, automation and third-party applications (for example the *arr suite) use the separate user with restricted access instead of the administrator credentials. Set the options RestrictedUsername and RestrictedPassword and pass them with any of the methods described above (the user-name/password part in the URL, basic authentication or X-Authorization: Basic ...). Such a user can read the queue and history and control downloads, but has no access to the administrator-only methods listed below. Each call to them fails with faultCode 401 and faultString "Access denied"; the same check is applied to every method called inside system.multicall.
Specifically, the restricted user:
- cannot change the configuration:
saveconfig,editserver,resetservervolume,testserver. Methodsconfigandloadconfigwork, but return***for the protected options (passwords, all feed URLs to prevent leaking indexer API keys and credentials, extension options, and security settings); - cannot control the daemon:
shutdown,reload,dump,clearlog,startupdate,logupdate,checkupdates; - cannot manage extensions or run scripts:
downloadextension,updateextension,deleteextension,testextension,startscript,logscript. Listing the cached extensions vialoadextensionsis allowed, but reloading them from disk (loadextensionswithloadFromDisk=true) is administrator-only; - cannot fetch arbitrary URLs or execute speed tests:
readurl,testserverspeed,testdiskspeed,testnetworkspeed; - can view the configured feeds (
viewfeed), but cannot preview a feed from an arbitrary client-supplied URL (previewfeed).
Security warning: HTTP authentication is not secure. Although the password is encoded using Base64 it is not encrypted. For secure communication use HTTPS: either enable the built-in TLS in NZBGet (SecureControl=yes, see options SecureCert, SecureKey, SecurePort) or put NZBGet behind a reverse proxy that terminates TLS (Traefik, Caddy, Nginx). When a trusted reverse proxy (running on the local host or listed in AuthorizedIP) forwards the header X-Forwarded-Proto: https, NZBGet marks the web-interface session cookie as Secure.
Features and limitations
- Multicalls are supported for
XML-RPCand not supported forJSON-RPC. - Introspection is not supported.
- Only positional parameters are supported in
JSON-RPC. Named parameters are not supported. Therefore parameter names are ignored but the order of parameters is important. All parameters are mandatory. - Each call to
JSON-P-RPChas one additional parameter - the name of callback-function. This parameter must be namedcallbackand must be passed first (before any other parameters). - 64 bit integers are returned in two separate fields
HiandLo(for exampleFileSizeHiandFileSizeLo). These fields are unsigned 32 bit integers. Although dynamic languages such as PHP or Python have no problems with these fields theXML-RPCspecification does not allow unsigned integers. This may cause troubles in statically typed languages such as Java or C++ ifXML-RPC-parser expects only signed integers in 32 bit range. As a solution useJSON-RPC(which does allow unsigned integers) instead ofXML-RPC.
Program control
Queue and history
Feeds
Status, logging and statistics
Pause and speed limit
Configuration
Extensions
Tests
Introduction
Installation manuals
- Installation on Windows
- Installation on Windows via WinGet
- Installation on macOS
- Installation on macOS via Homebrew
- Installation on Linux
- Installation on Docker
- Installation on Docker - LinuxServer.io version
- Installation on Android
- Installation on Synology
- Installation on QNAP
- Installation on other NAS devices
Building manuals
Configuration
- Backup And Restore Settings
- Performance Tips
- Choosing Cipher
- Behind Other Web Server
- TLS certificate verification
- What is the Default NZBGet Password?
- NZBGet Docker Setup Guide
- NZBGet Port Settings and Access Guide
- How to Configure NZBGet: Complete Setup Guide
- What Is Usenet?
- NZBGet 502 Error: Quick Fix Guide
- How to Upgrade from NZBGet v21.1 to the Latest NZBGet Version
- Slow NZBGet Speeds? Here’s How to Fix It
- NZBGet Performance Optimization Guide
- NZBGet Path and Folder Structure Guide
- How to Link NZBGet with Sonarr, Radarr, and Other Tools
- Sonarr vs VideoSort: How They Work with NZBGet
- NZBGet Storage Guide: Improve Performance with Smarter Path Setup
- How to Configure NZBGet on Android TV
- Using NZBGet with Sonarr and Radarr on Android TV
Performance tuning
- How to Optimize Usenet Performance in NZBGet
- NZBGet SystemHealth: Configuration and Environment Diagnostics
- Testing Usenet Speed and Performance in NZBGet
- Diagnosing and Maximizing Usenet Speeds in NZBGet
- Understanding Download Health in NZBGet
- Finding the Optimal Connection Count in NZBGet
- Primary vs Fill Servers Explained
- Understanding the Statistics Page in NZBGet
Usage
- Quick Filter
- Keyboard Shortcuts
- RSS and duplicate check
- VideoSort
- Console Mode
- Command Line Reference
- Performing Speed Tests
- NZBGet Interface Buttons Explained: What They Do and How to Use Them
- How to Use the NZBGet Status Tab
Development
Extensions
- Extension Scripts
- Post-processing scripts
- Scan Scripts
- Queue Scripts
- Scheduler Scripts
- Feed Scripts
- NZBGet Extension Manager: What It Is and How to Use It
- API reference
News server setup
- Astraweb
- BlockNews
- Cheapnews
- EasyNews
- Eweka
- FreeDiscussions
- Frugal Usenet
- GigaNews
- NewsDemon
- Newsgroup Ninja
- NewsgroupDirect
- Newshosting
- Pure Usenet
- SunnyUsenet
- Supernews
- theCubeNet
- ThunderNews
- TweakNews
- Usenet.Farm
- UsenetExpress
- UsenetServer
- UseNext
- ViperNews
- XLned
- XS News