Using The NZBGet-Compatible API

Weaver speaks NZBGet’s RPC protocol, so a client with an NZBGet option can drive it without a plugin or an adapter. Scryer, Sonarr, Radarr, Lidarr, and nzb360 have been tested against it. This guide covers connecting, authentication, and what each method does on Weaver’s side.

Connecting A Client

1. In Weaver, open Settings → Security → API Keys, create a key with the Control the queue scope, and copy it.

2. In the client, open Settings → Download Clients, click +, and choose NZBGet.

3. Fill in the form:

   Field	Value
   Host	Weaver’s hostname or IP. In Docker Compose, the service name, such as weaver.
   Port	9090 unless you changed it
   Use SSL	On only if a reverse proxy terminates TLS in front of Weaver. Weaver itself serves plain HTTP.
   URL Base	Leave empty unless Weaver runs under a --base-url prefix
   Username	weaver. Weaver ignores it.
   Password	The API key from step 1
   Category	A Weaver category or one of its aliases, such as tv for Sonarr or movies for Radarr

4. Click Test, then Save. The test calls version and config.

Priority and Add Paused map onto Weaver’s priority levels and paused submissions. Remove Completed and Remove Failed are safe to enable.

Scryer adds Weaver the same way, under Settings → Download Clients. See Storage Layout for the mount the two share. If you set WEAVER_HTTP_ALLOWED_HOSTS, add the hostname the client uses.

Scripts call /jsonrpc or /xmlrpc directly, POST only, behind the base URL if one is set: /weaver/jsonrpc. NZBGet’s /username:password/jsonrpc path form is not supported.

Authentication

Clients send the API key as the HTTP Basic password, and Weaver ignores the username. Scripts can send it as a Bearer token or an X-Api-Key header instead. If a request carries both, they must match. Browser cookies are never accepted on these endpoints, so even a signed-in browser needs a key.

Pick the narrowest scope for what the client does:

Scope	Methods it unlocks
Read	version, status, listgroups, listfiles, history, config, loadconfig, log, loadlog, postqueue, urlqueue, servervolumes
Control the queue	Everything above plus append, appendurl, editqueue, pausedownload, resumedownload, pausepost, resumepost, pausescan, resumescan, scheduleresume, rate, writelog, fetchfeeds, viewfeed, previewfeed
Admin	Everything above plus loadextensions

Sonarr, Radarr, and Scryer need Control the queue. A dashboard that only polls needs Read.

A missing or invalid key returns HTTP 401 before the body is read. A valid key without enough scope returns HTTP 403 with an NZBGet-style error envelope (code 401, Access denied). Method names are matched case-insensitively.

Browser extensions such as NZBUnity can call both endpoints from their extension origin with an API key.

A First Call

curl -u "weaver:$WEAVER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"version","params":[],"id":1}' \
  http://localhost:9090/jsonrpc

{"version":"1.1","id":1,"result":"16.0-weaver"}

The reported version is 16.0-weaver. Clients that gate features on NZBGet 16 or newer see everything they expect; the suffix identifies Weaver in their logs.

Responses use NZBGet’s JSON-RPC 1.1 envelope. An unknown method returns code 1 (Invalid procedure), a bad argument code 2 (Invalid parameter), and an editqueue command Weaver does not know code 3 (Invalid action). Request bodies may be up to 32 MiB, which is what a large NZB needs once base64-encoded.

Submitting A Download

append takes NZBGet’s positional arguments: filename, content, category, priority, add-to-top, add-paused, dupe key, dupe score, dupe mode, and the parameter list.

curl -u "weaver:$WEAVER_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg nzb "$(base64 < release.nzb)" \
    '{method:"append",params:["release.nzb",$nzb,"tv",0,false,false,"",0,"SCORE",[]],id:2}')" \
  http://localhost:9090/jsonrpc

What happens on Weaver’s side:

• Content may be base64 NZB text or an http(s) URL. URLs are fetched by Weaver with a 60 second timeout and up to ten redirects. Line-wrapped base64 is accepted.
• Category resolves to the Weaver category it names, by name or alias. Any other name becomes a folder of that name under the completed directory. A name that is not a safe folder name is rejected before anything is queued.
• Priority folds NZBGet’s numeric scale into Weaver’s three levels: below zero is Low, zero is Normal, above zero is High.
• Add paused creates the job paused. Add-to-top is accepted and ignored; use editqueue with GroupMoveTop to reorder.
• Duplicate handling honors the dupe key, score, and mode. The mode defaults to SCORE, as it does in NZBGet, and the values are kept on the job as nzbget.dupe_key, nzbget.dupe_score, and nzbget.dupe_mode.
• Parameters are read for two things. A drone parameter is kept on the job and echoed back in listgroups and history, which is how Sonarr and Radarr recognize their own submissions. A ScriptName: parameter set to yes or no selects post-processing scripts for that job and overrides the configured list; enabling a script that does not exist fails the call. Every other parameter is ignored, including *Unpack:Password. Set a password after the append with editqueue GroupSetParameter. A password meta tag inside the NZB, or {{password}} in the filename, also works.

The result is the new job’s ID, a positive integer. A malformed or empty NZB, or a submission blocked by duplicate policy, returns 0 rather than an error, exactly as NZBGet does.

appendurl is the pre-v13 shape (filename, category, priority, add-to-top, url) that nzb360 still uses. It returns true or false instead of the ID.

Reading The Queue And History

• status reports the download rate, the speed limit, paused flags, remaining size, free space in the completed directory (cached for five seconds, so a slow network mount cannot stall polling), and the counts the *arr clients read. A job that is still downloading while extraction has already started counts as active.
• listgroups lists one group per queued job with size, remaining bytes, status, category, priority, the Weaver stage in PostInfoText (for example Repairing (50%)), the Parameters array, and NZBID, which is Weaver’s job ID.
• listfiles lists the files in a job’s NZB with per-file progress.
• postqueue exposes jobs that are verifying, repairing, extracting, or moving, with stage progress.
• history returns finished jobs with the final path, the stage timings, and the same Parameters. Successful jobs report SUCCESS/ALL and cancelled jobs DELETED/MANUAL. Failed jobs report FAILURE/HEALTH whichever stage failed, which Sonarr and Radarr treat as a failed download.
• log and loadlog return the job event log in NZBGet’s entry shape.
• servervolumes reports per-server transfer, including the current quota window for servers that meter one.
• urlqueue is always empty; Weaver fetches URLs synchronously inside append.

Editing The Queue

editqueue accepts the v13+ shape (Command, Param, [IDs]) and the legacy (Command, Offset, Param, IDs…) shape. IDs are Weaver job IDs. Commands are case-insensitive. Up to 10,000 IDs per call.

Command	Weaver action
GroupPause, GroupResume	Pause or resume the job
GroupDelete, GroupParkDelete, GroupDupeDelete	Cancel the job
GroupFinalDelete	Cancel and drop it from history
GroupMoveTop, GroupMoveBottom, GroupMoveOffset	Reorder within the manual queue order
GroupSetCategory, GroupApplyCategory	Change the category
GroupSetPriority	Change the priority, folded to Low, Normal, or High
GroupSetParameter with Name=Value	Set a job parameter. *Unpack:Password=… sets the extraction password.
GroupSetDupeKey, GroupSetDupeScore, GroupSetDupeMode	Update the duplicate fields
GroupPauseAllPars, GroupPauseExtraPars	Return true. Weaver only fetches recovery data a repair needs, so this already holds.
HistoryDelete, HistoryFinalDelete	Remove the history entry
HistoryReturn, HistoryRedownload	Download the job again
HistoryProcess	Run post-processing again
HistoryMarkGood	Mark the history entry good

Commands with no Weaver equivalent return false instead of a fault, so a client’s plumbing keeps working: the anchor-relative moves and sort, renaming, every File* command, the HistorySet* edits, and HistoryMarkBad and HistoryMarkSuccess. A command aimed at a job that no longer exists also returns false.

Global Controls

• pausedownload and resumedownload (and their 2 variants) pause and resume all downloading.
• pausepost and resumepost pause and resume post-processing.
• pausescan and resumescan stop and restart the watch folder scanner.
• scheduleresume takes seconds until an automatic resume, from one second up to thirty days. The timer survives a restart.
• rate sets the download speed limit in KB/s, with 0 removing it. The change is persisted and shows in Weaver’s settings.
• writelog accepts a message and returns true.

Configuration And Feeds

config and loadconfig return the same values: MainDir, DestDir, ScriptDir, and a fixed KeepHistory of 7, which passes the *arr history check. Each Weaver category gets a CategoryN.* block with its destination directory, aliases, and default scripts. Its lowercase name and each alias without wildcards get blocks of their own, so clients such as nzb360 that read their category list here can pick any of them. If no categories are configured, a default set of tv, Movies, Music, Books, and Prowlarr is presented.

Weaver’s RSS feeds appear as FeedN.Name and FeedN.Interval entries, numbered contiguously. viewfeed takes that number and returns up to 500 items Weaver’s poller has already seen, marked fetched or backlog. previewfeed does the same and ignores NZBGet’s preview arguments. fetchfeeds triggers a poll. Feed URLs are never included in config, because they routinely embed indexer keys and config is readable with a Read key. That is also why the feed methods need Control scope.

loadextensions needs Admin scope. It lists the scripts directory and returns true; the script details themselves are managed in Weaver’s UI.

XML-RPC

Everything above is available at /xmlrpc with the same authentication and semantics. Entities in values are decoded, so passwords and indexer URLs containing &, <, or quotes arrive intact. Faults carry the same codes as the JSON-RPC errors.

What Is Not There

• No SABnzbd-compatible API. Clients must use their NZBGet option.
• No per-file control. File* commands return false; Weaver schedules whole jobs.
• No renaming from the API. Job names come from the NZB.
• No history edits. HistorySet* commands return false. A history entry can be deleted, downloaded again, post-processed again, or marked good.
• No extension management. Scripts are installed by dropping them into the scripts directory. See Post-Processing Scripts.

Related

• API And Metrics covers the GraphQL API and Prometheus metrics.
• Security And Access explains the three key scopes.
• Storage Layout sets up the mount Scryer and Weaver share.