NZBCloud : API reference

Status of this document

The document describes methods available in NZBCloud version 21.1 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. Feel free to contact us with any questions.

Protocols

NZBCloud 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 NZBCloud are equal: all methods are identical. You may choose the protocol, which is better supported by your programming language.

Authentication

NZBCloud authenication pair (username/password)

  • https://downloader.nzbcloud.com/username:password/xmlrpc

Features and limitations

  • Multicalls are supported for XML-RPC and not supported for JSON-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-RPC has one additional parameter - the name of callback-function. This parameter must be named “callback” and must be passed first (before any other parameters).
  • 64 bit integers are returned in two separate fields ‘‘Hi’’ and ‘‘Lo’’ (for example ‘‘FileSizeHi’’ and ‘‘FileSizeLo’’). These fields are unsigned 32 bit integers. Although dynamic languages such as PHP or Python have no problems with these fields the XML-RPC specification does not allow unsigned integers. This may cause troubles in statically typed languages such as Java or C++ if XML-RPC-parser expects only signed integers in 32 bit range. As a solution use JSON-RPC instead (which does allow unsigned integers) instead of XML-RPC.

Program control

Syntax
string version()

Request the version-string of the program.

Return value
Version string.
21.1 #CONST
Syntax
string reload()

Stop all activities and reinitialize the program. This method must be called after changing of program options for them to have effect.

Return value
true #CONST
Syntax
bool reload()

Stop all activities and reinitialize the program. This method must be called after changing of program options for them to have effect.

Return value
true #CONST

Queue and history

Syntax
struct[] listgroups(int NumberOfLogEntries)

Request for list of downloads (nzb-files). This method returns summary information for each group (nzb-file).

Return value

This method returns array of structures with following fields:

FirstID: numericId, #ID in NZBCloud system 
LastID: numericId, #ID in NZBCloud system
NZBID: numericId, #ID in NZBCloud system
NZBFilename: fileName, #Download name in NZBCloud system
NZBName: fileName, #Download name in NZBCloud system
Kind: 'NZB', #CONST
URL: "", #CONST
DestDir: `/${storageID}`, #where storageID is userID in NZBCloud system 
FinalDir: `/${storageID}`, #where storageID is userID in NZBCloud system 
Category: targetStorage, #GOOGLEDRIVE, ONEDRIVE, DROPBOX, NZBCLOUD
FileSizeLo: total * 1024 * 1024, #Download size bytes 
FileSizeHi: total * 1024 * 1024, #Download size bytes
FileSizeMB: total, #Download size megabytes
RemainingSizeLo: (total - downloaded) * 1024 * 1024, #Remaining download size bytes
RemainingSizeHi: (total - downloaded) * 1024 * 1024, #Remaining download size bytes
RemainingSizeMB: total - downloaded, #Remaining download size megabytes
PausedSizeLo: 0, #CONST
PausedSizeHi: 0, #CONST
PausedSizeMB: 0, #CONST
FileCount: 0, #CONST
RemainingFileCount: 0, #CONST
RemainingParCount: 0, #CONST
MinPostTime: 0, #CONST
MaxPostTime: 0, #CONST
MaxPriority: 0, #CONST
ActiveDownloads: 1, #CONST
Status: listGroupStatus, #DOWNLOADING, QUEUED, UNPACKING, MOVING, QUEUED
TotalArticles: 0, #CONST
SuccessArticles: 0, #CONST
FailedArticles: 0, #CONST
Health: 1000, #CONST
CriticalHealth: 0, #CONST
DownloadedSizeLo: downloaded * 1024 * 1024, #Downloaded size bytes
DownloadedSizeHi: downloaded * 1024 * 1024, #Downloaded size bytes
DownloadedSizeMB: downloaded, #Downloaded size megabytes
DownloadTimeSec: downloadTime, #Downloaded time seconds
MessageCount: 0, #CONST
DupeKey: '', #CONST
DupeScore: 0, #CONST
DupeMode: 'SCORE', #CONST
Parameters: [], #CONST
ServerStats: [{ ServerID: 1, SuccessArticles: 0, FailedArticles: 0 }], #CONST
PostStageProgress: postProgress * 10, #Post progress
PostTotalTimeSec: postTotalTime, #Total post process time
UnpackTimeSec: 0, #CONST
UnpackStatus: 'NONE', #CONST
PostInfoText: 'NONE', #CONST
PostStageTimeSec: 0, #CONST
Syntax
struct[] listfiles(int IDFrom, int IDTo, int NZBID)

Request for file’s list of a group (nzb-file).

Return value

This method returns an array of structures with following fields:

[] #CONST
Signature
struct[] history(bool Hidden)

Request for list of items in history-list.

Return value

This method returns an array of structures with following fields:

ID: numericId, #ID in NZBCloud system
NZBID: numericId, #ID in NZBCloud system
Kind: 'NZB', #CONST
NZBFilename: fileName, #Download name in NZBCloud system
Name: fileName, #Download name in NZBCloud system
URL: '', #CONST
HistoryTime: 0, #CONST
DestDir: `/${storageID}`, #user ID in NZBCloud system 
FinalDir: `/${storageID}`, #user ID in NZBCloud system 
Category: targetStorage, #GOOGLEDRIVE, ONEDRIVE, DROPBOX, NZBCLOUD
FileSizeLo: total * 1024 * 1024, #Download size bytes 
FileSizeHi: total * 1024 * 1024, #Download size bytes 
FileSizeMB: total, #Download size megabytes
FileCount: 0, #CONST
RemainingFileCount: 0, #CONST
MinPostTime: 0, #CONST
MaxPostTime: 0, #CONST
TotalArticles: 0, #CONST
SuccessArticles: 0, #CONST
FailedArticles: 0, #CONST
Health: 1000, #CONST
DownloadedSizeLo: 0, #CONST
DownloadedSizeHi: 0, #CONST
DownloadedSizeMB: total, #Downloaded size megabytes
DownloadTimeSec: 0, #CONST
PostTotalTimeSec: postTotalTime, #Total post process time
ParTimeSec: 0, #CONST
RepairTimeSec: 0, #CONST
UnpackTimeSec: 0, #CONST
MessageCount: 0, #CONST
DupeKey: '', #CONST
DupeScore: 0, #CONST
DupeMode: 'SCORE', #CONST 
ParStatus: 'SUCCESS', #CONST 
ExParStatus: 'RECIPIENT', #CONST 
UnpackStatus, #PASSWORD, SUCCESS
UrlStatus: 'NONE', #CONST 
ScriptStatus: 'NONE', #CONST 
ScriptStatuses: ['NONE'], #CONST
MoveStatus: 'SUCCESS', #CONST
DeleteStatus: 'NONE', #CONST
MarkStatus: 'NONE', #CONST
ExtraParBlocks: 0, #CONST
Parameters: [], #CONST
Status: historyStatus, #FAILURE/BAD, FAILURE/HEALTH, SUCCESS/ALL, FAILURE/BAD, WARNING/SPACE, WARNING/PASSWORD
ServerStats: [{ ServerID: 1, SuccessArticles: 0, FailedArticles: 0 }], #CONST
Signature
int append(string NZBFilename)

Add nzb-file or URL to download queue.

Parameters
  • NZBFilename (string) – name of nzb-file (with extension). This parameter can be an empty string if parameter Content contains an URL; in that case the file name is read from http headers. If NZBFilename is provided it must have correct extension (usually “.nzb”) according to file content. Files without “.nzb”-extension are not added to queue directly; all files however are sent to scan-scripts.
Return value
number #ID in NZBCloud system
Signature
bool editqueue(string Command, string Param, int[] IDs)

Edit items in download queue or in history.

Parameters
  • Command (string) – one of the following commands:
    • FileMoveOffset – Move files relative to the current position in queue. v18.0 Param contains offset. v18.0 Offset is passed in Offset.
    • FileMoveTop – Move files to top of queue.
    • FileMoveBottom – Move files to bottom of queue.
    • FilePause – Pause files.
    • FileResume – Resume (unpause) files.
    • FileDelete – Delete files.
    • FilePauseAllPars – Pause only pars (does not affect other files).
    • FilePauseExtraPars – Pause only pars, except main par-file (does not affect other files).
    • FileSetPriority – v13.0 Deprecated, use GroupSetPriority instead.
    • FileReorder – Reorder files in the group. The list of IDs may include files only from one group.
    • FileSplit – Split nzb-file. The list of IDs contains the files to move into new download item.
    • GroupMoveOffset – Move groups relative to the current position in queue. v18.0 Param contains offset. v18.0 Offset is passed in Offset.
    • GroupMoveTop – Move groups to top of queue.
    • GroupMoveBottom – Move groups to bottom of queue.
    • GroupPause – Pause groups.
    • GroupResume – Resume (unpause) groups.
    • GroupDelete – Delete groups and put to history.
    • GroupDupeDelete – Delete groups, put to history and mark as duplicate.
    • GroupFinalDelete – Delete groups without adding to history.
    • GroupPauseAllPars – Pause only pars (does not affect other files).
    • GroupPauseExtraPars – Pause only pars, except main par-file (does not affect other files).
    • GroupSetPriority – Set priority for all files in group. Param contains priority value.
    • GroupSetCategory – Set category for group. Param contains category name.
    • GroupApplyCategory – Set or change category for groups and reassign pp-params according to category settings. Param contains category name.
    • GroupMerge – Merge groups.
    • GroupSetParameter – Set post-processing parameter for group. Param contains string in form of Paramname=Paramvalue.
    • GroupSetName – Rename group. Param contains new name.
    • GroupSetDupeKey – Set duplicate key. Param contains duplicate key. See RSS.
    • GroupSetDupeScore – Set duplicate score. Param contains duplicate score. See RSS.
    • GroupSetDupeMode – Set duplicate mode. Param contains one of SCORE, ALL, FORCE. See RSS.
    • GroupSort – v15.0 Sort selected or all groups. Parameter Param must be one of: name, priority, category, size, left; add character + or – to sort to explicitly define ascending or descending order (for example name-); if none of these characters is used the auto-mode is active: the items are sorted in ascending order first, if nothing changed – they are sorted again in descending order. Parameter IDs contains the list of groups to sort; pass empty array to sort all groups.
    • PostMoveOffset – v13.0 Deprecated, use GroupMoveOffset instead.
    • PostMoveTop – v13.0 Deprecated, use GroupMoveTop instead.
    • PostMoveBottom – v13.0 Deprecated, use GroupMoveBottom instead.
    • PostDelete – Delete post-jobs.
    • HistoryDelete – Hide history items (mark as hidden).
    • HistoryFinalDelete – Delete history items.
    • HistoryReturn – Return history items back to download queue.
    • HistoryProcess – Post-process history items again.
    • HistoryRedownload – Move history items back to download queue for redownload.
    • HistorySetName – v15.0 Rename history item. Param contains new name.
    • HistorySetCategory – v15.0 Set category for history item. Param contains category name.
    • HistorySetParameter – Set post-processing parameter for history items. Param contains string in form of Paramname=Paramvalue.
    • HistorySetDupeKey – Set duplicate key. Param contains duplicate key. See RSS.
    • HistorySetDupeScore – Set duplicate score. Param contains duplicate score. See RSS.
    • HistorySetDupeMode – Set duplicate mode. Param contains one of SCORE, ALL, FORCE. See RSS.
    • HistorySetDupeBackup – Set use as duplicate backup-flag for history items. Param contains 0 or 1. See RSS.
    • HistoryMarkBad – Mark history item as bad (and download other duplicate). See RSS.
    • HistoryMarkGood – Mark history item as good. See RSS.
    • HistoryMarkSuccess – v15.0 Mark history item as success. See RSS.
  • Offset (int) – v18.0 offset for commands FileMoveOffset and GroupMoveOffset. For all other commands must be “0”. v18.0 Offset is passed in Param and parameter Offset should not be passed at all.
  • Param (string) – additional parameter if mentioned in the command description, otherwise an empty string.
  • IDs (struct[]) – array of IDs (as integers).
    • File-commands (FileXXX) need ID of file.
    • All other commands need NZBID.
Return value
“True” on success or “False” on failure.
Signature
bool scan()

Request rescanning of incoming directory for nzb-files (option NzbDir).

Return value
true #CONST

Status, logging and statistics

Syntax
struct status()

Request for current status (summary) information.

Return value

This method returns structure with following fields:

RemainingSizeLo: 0, #CONST
RemainingSizeHi: 0, #CONST
RemainingSizeMB: 0, #CONST
ForcedSizeLo: 0, #CONST
ForcedSizeHi: 0, #CONST
ForcedSizeMB: 0, #CONST
DownloadedSizeLo: 0, #CONST
DownloadedSizeHi: 0, #CONST
DownloadedSizeMB: 0, #CONST
ArticleCacheLo: 0, #CONST
ArticleCacheHi: 0, #CONST
ArticleCacheMB: 0, #CONST
DownloadRate, #Download speed
AverageDownloadRate: 0, #CONST
DownloadLimit: 0, #CONST
ThreadCount: 1, #CONST
PostJobCount: 0, #CONST
UrlCount: 0, #CONST
UpTimeSec: 600, #CONST
DownloadTimeSec: 0, #CONST
DownloadPaused: false, #CONST
ServerStandBy: true, #CONST
PostPaused: false, #CONST
ScanPaused: false, #CONST
ServerTime: Date.now(), #Current date
FreeDiskSpaceLo: 107374182400, #CONST
FreeDiskSpaceHi: 107374182400, #CONST
FreeDiskSpaceMB: 102400, #CONST
ResumeTime: 0, #CONST
FeedActive: false, #CONST
NewsServers: [{ "ID": 1, "Active": true, }] #CONST
Syntax
struct[] log(int IDFrom, int NumberOfEntries)

 

Return value
[] #CONST
Signature
bool writelog(string Kind, string Text)

Append log-entry into server’s log-file and on-screen log-buffer.

Parameters
  • Kind (string) – Kind of log-message. Must be one of the following strings: INFO, WARNING, ERROR, DETAIL, DEBUG. Debug-messages are available, only if the program was compiled in debug-mode.
  • Text (string) – Text to be added into log.
Return value
true #CONST
Signature
struct[] loadlog(int NZBID, int IDFrom, int NumberOfEntries)

Loads from disk and returns nzb-log for a specific nzb-file.

Parameters
  • NZBID (int) – id of nzb-file.
Return value
[] #CONST
Signature
struct[] servervolumes()

Returns download volume statistics per news-server.

Return value
[] #CONST
Signature
bool resetservervolume(int ServerId, string Sounter)

Reset download volume statistics for a specified news-server.

Return value
false #CONST

Pause and speed limit

Syntax
bool rate(int Limit)

Set download speed limit.

Parameters
  • Limit (int) – new download speed limit in KBytes/second. Value “0” disables speed throttling.
Return value
true #CONST
Syntax
bool pausedownload()

Pause download queue

Return value
true #CONST
Signature
bool resumedownload()

Resume (previously paused) download queue.

Return value
true #CONST
Signature
bool pausepost()

Pause post-processing.

Return value
true #CONST
Signature
bool resumepost()

Resume (previously paused) post-processing.

Return value
true #CONST
Signature
bool pausescan()

Pause scanning of directory with incoming nzb-files (option NzbDir).

Return value
true #CONST
Signature
bool resumescan()

Resume (previously paused) scanning of directory with incoming nzb-files (option NzbDir).

Return value
true #CONST
Signature
bool scheduleresume(int Seconds)

Schedule resuming of all activities after expiring of wait interval.

Parameters
  • Seconds (int) – Amount of seconds to wait before resuming.
Return value
true #CONST
Remarks

Method scheduleresume activates a wait timer. When the timer fires then all pausable activities resume: download, post-processing and scan of incoming directory. This method doesn’t pause anything, activities must be paused before calling this method.

Calling any of methods pausedownload, resumedownload, pausepost, resumepost, pausescan, resumescan deactivates the wait timer.

Configuration

Syntax
struct[] config()

Returns current configuration loaded into program. Please note that the configuration file on disk may differ from the loaded configuration. This may occur if the configuration file on disk was changed after the program was launched or the program may get some options passed via command line.

Return value
[] #CONST
Remarks
  • For options with predefined possible values (yes/no, etc.) the values are returned always in lower case.
  • If the option has variable references (e. g. “${MainDir}/dst”) the returned value has all variables substituted (e. g. “/home/user/downloads/dst”).
Syntax
string reload()

Stop all activities and reinitialize the program. This method must be called after changing of program options for them to have effect.

Return value
[] #CONST
Signature
string reload()

Shutdown the program.

Return value
[] #CONST
Signature
string reload()

Shutdown the program.

Return value
[] #CONST