RPC API reference

From NZBGet
Jump to: navigation, search

Contents

About XML-RPC and JSON-RPC in NZBGet

Status of this document

The document describes methods available in NZBGet version 12.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. If you need information for older NZBGet version please see a historical article RPC API reference 0.6.0-12.0.

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.

The RPC server uses HTTP basic authentication with username and password from server's configuration file. The URL would be something like:

If HTTP basic authentication is somewhat problematic the username/password can also be passed in the URL as the first part of the path:

Security warning: HTTP authentication is not secure. Although the password is encoded using Base64 it is not encrypted. For secure communication use HTTPS (needs to be explicitly enabled in NZBGet settings by user).

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).

Program control

Method "version"

Signature:

string version() 

Request the version-string of the program.

Return value: Version string.

Method "shutdown"

Signature:

bool shutdown() 

Shutdown the program.

Return value: Always "True".

Method "reload"

Signature:

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: Always "True".

Queue and history

Method "listgroups"

Signature:

struct[] listgroups(int NumberOfLogEntries) 

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

Parameters:

  • NumberOfLogEntries - 13.0 Number of post-processing log-entries (field Log), which should be returned for the top (currently processing) item in post-processing state.

Return value: This method returns an array of structures with following fields:

Field Type Description
NZBID int ID of NZB-file.
FirstID int 13.0 ID of the first file in download queue, belonging to the group. Deprecated, in v13 has the same value as NZBID (for compatibility with software using this field when calling method editqueue).
LastID int 13.0 ID of the last file in download queue, belonging to the group. Deprecated, in v13 has the same value as NZBID (for compatibility with software using this field when calling method editqueue).
NZBFilename string Name of nzb-file, this file was added to queue from. The filename could include fullpath (if client sent it by adding the file to queue).
NZBName string The name of nzb-file without path and extension. Ready for user-friendly output.
NZBNicename string 13.0 Deprecated, use NZBName instead.
Kind string 13.0 Kind of queue entry: NZB or URL.
URL string 13.0 URL where the NZB-file was fetched (Kind=NZB) or should be fetched (Kind=URL).
DestDir string Destination directory for output file.
FinalDir string Final destination if set by one of post-processing scripts. Can be set only for items in post-processing state.
Category string Category for group or empty string if none category is assigned.
FileSizeLo int Initial size of all files in group in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Initial size of all files in group in bytes, High 32-bits of 64-bit value.
FileSizeMB int Initial size of all files in group in megabytes.
RemainingSizeLo int Remaining size of all (remaining) files in group in bytes, Low 32-bits of 64-bit value.
RemainingSizeHi int Remaining size of all (remaining) files in group in bytes, High 32-bits of 64-bit value.
RemainingSizeMB int Remaining size of all (remaining) files in group in megabytes.
PausedSizeLo int Size of all paused files in group in bytes, Low 32-bits of 64-bit value.
PausedSizeHi int Size of all paused files in group in bytes, High 32-bits of 64-bit value.
PausedSizeMB int Size of all paused files in group in megabytes.
FileCount int Initial number of files in group.
RemainingFileCount int Remaining (current) number of files in group.
RemainingParCount int Remaining (current) number of par-files in group.
MinPostTime int Date/time when the oldest file in the group was posted to newsgroup (Time is in C/Unix format).
MaxPostTime int Date/time when the newest file in the group was posted to newsgroup (Time is in C/Unix format).
MinPriority int 13.0 In v12: the lowest priority of files in the group. The files in the group can have different priorities. Deprecated, use MaxPriority instead.
MaxPriority int In v13: priority of the group. In v12: the highest priority of files in the group. The files in the group can have different priorities.
ActiveDownloads int Number of active downloads in the group. With this filed can be determined what group(s) is (are) being currently downloaded. In most cases only one group is downloaded at a time however more that one group can be downloaded simultaneously when the first group is almost completely downloaded.
Status string 13.0 Status of the group:
  • QUEUED - queued for download;
  • PAUSED - paused;
  • DOWNLOADING - item is being downloaded;
  • FETCHING - nzb-file is being fetched from URL (Kind=URL);
  • PP_QUEUED - queued for post-processing (completely downloaded);
  • LOADING_PARS - stage of par-check;
  • VERIFYING_SOURCES - stage of par-check;
  • REPAIRING - stage of par-check;
  • VERIFYING_REPAIRED - stage of par-check;
  • RENAMING - processed by par-renamer;
  • UNPACKING - being unpacked;
  • MOVING - moving files from intermediate directory into destination directory;
  • EXECUTING_SCRIPT - executing post-processing script;
  • PP_FINISHED - post-processing is finished, the item is about to be moved to history.
TotalArticles int Total number of articles in all files of the group.
SuccessArticles int Number of successfully downloaded articles.
FailedArticles int Number of failed article downloads.
Health int Current health of the group, in permille. 1000 means 100.0%. The health can go down below this valued during download if more article fails. It can never increase (unless merging of groups). Higher values are better. See forum topic Download health monitoring.
CriticalHealth int Calculated critical health of the group, in permille. 1000 means 100.0%. The critical health is calculated based on the number and size of par-files. Lower values are better.
DupeKey string Duplicate key. See RSS#Duplicates.
DupeScore int Duplicate score. See RSS#Duplicates.
DupeMode string Duplicate mode. One of SCORE, ALL, FORCE. See RSS#Duplicates.
Parameters array Post-processing parameters for group. See below.
Deleted bool 12.0 Deprecated, use DeleteStatus instead.
ServerStats array Per news-server download statistics. For description see method #history.
ParStatus, UnpackStatus, MoveStatus, ScriptStatus, DeleteStatus, MarkStatus, ScriptStatuses string These fields have meaning only for a group which is being currently post-processed. For description see method #history.
PostInfoText string 13.0 Text with short description of current action in post processor. For example: "Verifying file myfile.rar". Only for a group which is being currently post-processed.
PostStageProgress int 13.0 Completing of current stage. A number in the range 0..1000. Divide it to 10 to get percent-value. Only for a group which is being currently post-processed.
PostTotalTimeSec int 13.0 Number of seconds this post-job is being processed (after it first changed the state from PP-QUEUED). Only for a group which is being currently post-processed.
PostStageTimeSec int 13.0 Number of seconds the current stage is being processed. Only for a group which is being currently post-processed.
Log array 13.0 Array of structs with log-messages. For description of struct see method log. Only for a group which is being currently post-processed. The number of returned entries is limited by parameter NumberOfLogEntries.

Field Parameters is an array of structures with following fields:

Field Type Description
Name string Name of post-processing parameter.
Value string Value of post-processing parameter.

NOTE: In v12 there is no field Status in the group. The status can be determined by examining other fields. See forum topic Status of group with API.

Method "listfiles"

Signature:

struct[] listfiles(int IDFrom, int IDTo, int NZBID) 

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

Parameters:

  • IDFrom - 12.0 The first ID of file range to be returned. Deprecated, must be 0.
  • IDTo - 12.0 The last ID of file range to be returned. Deprecated, must be 0.
  • NZBID - The NZBID of the group to be returned.

To get the list of all files from all groups set all parameters to 0.

Return value: This method returns an array of structures with following fields:

Field Type Description
ID int ID of file.
NZBID int ID of NZB-file.
NZBFilename string Name of nzb-file. The filename could include fullpath (if client sent it by adding the file to queue).
NZBName string The name of nzb-file without path and extension. Ready for user-friendly output.
NZBNicename string 12.0 Deprecated, use NZBName instead.
Subject string Subject of article (read from nzb-file).
Filename string Filename parsed from subject. It could be incorrect since the subject not always correct formated. After the first article for file is read, the correct filename is read from article body.
FilenameConfirmed bool "True" if filename was already read from article's body. "False" if the name was parsed from subject. For confirmed filenames the destination file on disk will be exactly as specified in field "filename". For unconfirmed filenames the name could change later.
DestDir string Destination directory for output file.
FileSizeLo int Filesize in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Filesize in bytes, High 32-bits of 64-bit value.
RemainingSizeLo int Remaining size in bytes, Low 32-bits of 64-bit value.
RemainingSizeHi int Remaining size in bytes, High 32-bits of 64-bit value.
Paused bool "True" if file is paused.
PostTime int Date/time when the file was posted to newsgroup (Time is in C/Unix format).
Priority int 13.0 Priority of the file. Deprecated, use MaxPriority of the group (method listgroups) instead.
ActiveDownloads int Number of active downloads for the file. With this filed can be determined what file(s) is (are) being currently downloaded.

Method "history"

Signature:

struct[] history(bool Hidden) 

Request for list of items in history-list.

Parameters:

  • Hidden - Also return hidden history records. Use this only if you need to see the old (hidden) history records (Kind=DUP). Normal (unhidden) records are always returned.

Return value: This method returns an array of structures with following fields:

Field Type Description
NZBID int ID of NZB-file.
ID int 13.0 Deprecated, use NZBID instead.
Kind string Kind of history item. One of the predefined text constants:
  • NZB for nzb-files;
  • URL for failed URL downloads;
  • DUP for hidden history items.

NOTE: successful URL-downloads result in adding files to download queue, a success-history-item is not created in this case.

NZBFilename string Name of nzb-file, this file was added to queue from. The filename could include fullpath (if client sent it by adding the file to queue).
Name string The name of nzb-file or info-name of URL, without path and extension. Ready for user-friendly output.
NZBNicename string 12.0 Deprecated, use Name instead.
URL string URL.
DestDir string Destination directory for output files.
FinalDir string Final destination if set by one of post-processing scripts. Can be set only for items in post-processing state.
Category string Category for group or empty string if none category is assigned.
FileSizeLo int Initial size of all files in group in bytes, Low 32-bits of 64-bit value.
FileSizeHi int Initial size of all files in group in bytes, High 32-bits of 64-bit value.
FileSizeMB int Initial size of all files in group in megabytes.
FileCount int Initial number of files in group.
RemainingFileCount int Number of parked files in group. If this number is greater than "0", the history item can be returned to download queue using command "HistoryReturn" of method "editqueue".
HistoryTime int Date/time when the file was added to history (Time is in C/Unix format).
Status string 13.0 Total status of the download. One of the predefined text constants such as SUCCESS/ALL or FAILURE/UNPACK, etc. For the complete list see below.
ParStatus string Result of par-check/repair:
  • NONE - par-check wasn't performed;
  • FAILURE - par-check has failed;
  • REPAIR_POSSIBLE - download is damaged, additional par-files were downloaded but the download was not repaired. Either the option ParRepair is disabled or the par-repair was cancelled by option ParTimeLimit;
  • SUCCESS - par-check was successful;
  • MANUAL - download is damaged but was not checked/repaired because option ParCheck is set to Manual.
UnpackStatus string Result of unpack:
  • NONE - unpack wasn't performed, either no archive files were found or the unpack is disabled for that download or globally;
  • FAILURE - unpack has failed;
  • SPACE - unpack has failed due to not enough disk space;
  • PASSWORD - unpack has failed because the password was not provided or was wrong. Only for rar5-archives;
  • SUCCESS - unpack was successful.
UrlStatus string Result of URL-download:
  • NONE - that nzb-file were not fetched from an URL;
  • SUCCESS - that nzb-file was fetched from an URL;
  • FAILURE - the fetching of the URL has failed.
  • SCAN_SKIPPED - The URL was fetched successfully but downloaded file was not nzb-file and was skipped by the scanner;
  • SCAN_FAILURE - The URL was fetched successfully but an error occurred during scanning of the downloaded file. The downloaded file isn't a proper nzb-file. This status usually means the web-server has returned an error page (HTML page) instead of the nzb-file.
ScriptStatus string Accumulated result of all post-processing scripts. One of the predefined text constants: NONE, FAILURE, SUCCESS. Also see field ScriptStatuses.
ScriptStatuses array Status info of each post-processing script. See below.
MoveStatus string Result of moving files from intermediate directory into final directory:
  • NONE - the moving wasn't made because either the option InterDir is not in use or the par-check or unpack have failed;
  • SUCCESS - files were moved successfully;
  • FAILURE - the moving has failed.
DeleteStatus string Indicates if the download was deleted:
  • NONE - not deleted;
  • MANUAL - the download was manually deleted by user;
  • HEALTH- the download was deleted by health check;
  • DUPE - the download was deleted by duplicate check.
MarkStatus string Indicates if the download was marked by user:
  • NONE - not marked;
  • GOOD - the download was marked as good by user using command Mark as good in history dialog;
  • BAD - the download was marked as bad by user using command Mark as bad in history dialog;
Parameters array Post-processing parameters for group. For description of struct see method listgroups.
ServerStats array Per-server article completion statistics. See below.
Log array 13.0 Deprecated, was never really used.

Field Status

13.0 Field Status can be set to one of the following values:

  • For history items with Kind=NZB:
Status Description
FAILURE/BAD The download was marked as bad by user using command Mark as bad in history dialog.
SUCCESS/GOOD The download was marked as good by user using command Mark as good in history dialog.
FAILURE/HEALTH The download was aborted by health check.
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/PAR The par-check has failed.
FAILURE/UNPACK The unpack has failed and there are no par-files.
FAILURE/MOVE An error has occurred when moving files from intermediate directory into the final destination directory.
WARNING/DAMAGED Par-check is required by is disabled in settings (option ParCheck=Manual).
WARNING/REPAIRABLE Par-check has detected damage and has downloaded additional par-files but the repair is disabled in settings (option ParRepair=no).
FAILURE/HEALTH Download health is below critical health. No par-check was made (there are no par-files). No unpack was made (there are no archive files or unpack was disabled for that download or globally).
WARNING/HEALTH Download health is below 100.0%. No par-check was made (there are no par-files). No unpack was made (there are no archive files or unpack was disabled for that download or globally).
SUCCESS/HEALTH Download was successful, download health is 100.0%. No par-check was made (there are no par-files). No unpack was made (there are no archive files or unpack was disabled for that download or globally).
WARNING/SPACE Unpack has failed due to not enough space on the drive.
WARNING/PASSWORD Unpack has failed because the password was not provided or was wrong. Only for rar5-archives.
SUCCESS/ALL Downloaded and par-checked or unpacked successfully. All post-processing scripts were successful. The download is completely OK.
SUCCESS/UNPACK Similar to SUCCESS/ALL but no post-processing scripts were executed. Downloaded and unpacked successfully. Par-check was successful or was not necessary.
SUCCESS/PAR Similar to SUCCESS/ALL but no post-processing scripts were executed. Downloaded and par-checked successfully. No unpack was made (there are no archive files or unpack was disabled for that download or globally).
WARNING/SCRIPT Downloaded successfully. Par-check and unpack were either successful or were not performed. At least one of the post-processing scripts has failed.
  • For history items with Kind=URL:
Status Description
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/FETCH Fetching of the URL has failed.
WARNING/SKIPPED The URL was fetched successfully but downloaded file was not nzb-file and was skipped by the scanner.
FAILURE/SCAN The URL was fetched successfully but an error occurred during scanning of the downloaded file. The downloaded file isn't a proper nzb-file. This status usually means the web-server has returned an error page (HTML page) instead of the nzb-file.
  • For history items with Kind=DUP:
Status Description
SUCCESS/HIDDEN The hidden history item has status SUCCESS.
FAILURE/HIDDEN The hidden history item has status FAILURE.
DELETED/MANUAL The download was manually deleted by user.
DELETED/DUPE The download was deleted by duplicate check.
FAILURE/BAD The download was marked as bad by user using command Mark as bad in history dialog.
SUCCESS/GOOD The download was marked as good by user using command Mark as good in history dialog.

Method "append"

13.0 Signature:

int append(string NZBFilename, string NZBContent, string Category, int Priority, bool AddToTop,
      bool AddPaused, string DupeKey, int DupeScore, string DupeMode)

13.0 Signature:

bool append(string NZBFilename, string Category, int Priority, bool AddToTop, string Content,
      bool AddPaused, string DupeKey, int DupeScore, string DupeMode)

Add nzb-file or URL to download queue.

Parameters:

  • NZBFilename - name of nzb-file. Server uses the name to build destination directory. This name can contain full path or only filename.
  • Content - content of nzb-file encoded with Base64 (see #Examples) or URL to fetch nzb-file from. V12 can not process URLs in this method and requires the usage of a separate method appendurl.
  • Category - category for nzb-file. Can be empty string.
  • Priority - priority for nzb-file. 0 for "normal priority", positive values for high priority and negative values for low priority. Downloads with priorities equal to or greater than 900 are downloaded and post-processed even if the program is in paused state (force mode). Default priorities are: -100 (very low), -50 (low), 0 (normal), 50 (high), 100 (very high), 900 (force).
  • AddToTop - "True" if the file should be added to the top of the download queue or "False" if to the end.
  • AddPaused - "True" if the file should be added in paused state.
  • DupeKey - duplicate key for nzb-file. See RSS#Duplicates.
  • DupeScore - duplicate score for nzb-file. See RSS#Duplicates.
  • DupeMode - duplicate mode for nzb-file. See RSS#Duplicates.

13.0 Return value: Positive number representing NZBID of the queue item. 0 and negative numbers represent error codes. Current version uses only error code 0, newer versions may use other error codes for detailed information about error.

13.0 Return value: "True" on success or "False" on failure.

NOTE: For backward compatibility v13 can also process calls made by apps written for older NZBGet versions (v12 or older). The new (v13) method signature has a different order of parameters than v12 had; this allows NZBGet to detect if the call is made for old method or for new. The return value (integer or boolean) depends on this. The old method should not be used in new apps.

Method "editqueue"

Signature:

bool editqueue(string Command, int Offset, string EditText, int[] IDs) 

Edit items in download queue or in history.

Parameters:

  • Command - one of the following commands:
Command Description
FileMoveOffset Move files to Offset relative to the current position in queue.
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 13.0 Set file priority. EditText contains priority value. 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 to Offset relative to the current position in queue.
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. EditText contains priority value.
GroupSetCategory Set category for group. EditText contains category name.
GroupApplyCategory 13.0 Set or change category for groups and reassign pp-params according to category settings. EditText contains category name.
GroupMerge Merge groups.
GroupSetParameter Set post-processing parameter for group. EditText contains string in form of Paramname=Paramvalue.
GroupSetName Rename group.
GroupSetDupeKey Set duplicate key. EditText contains duplicate key. See RSS#Duplicates.
GroupSetDupeScore Set duplicate score. EditText contains duplicate score. See RSS#Duplicates.
GroupSetDupeMode Set duplicate mode. EditText contains one of SCORE, ALL, FORCE. See RSS#Duplicates.
PostMoveOffset 13.0 Move post-job to Offset relative to the current position in queue. Deprecated, use GroupMoveOffset instead.
PostMoveTop 13.0 Move post-job to top of queue. Deprecated, use GroupMoveTop instead.
PostMoveBottom 13.0 Move post-job to bottom of queue. 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.
HistorySetParameter Set post-processing parameter for history items. EditText contains string in form of Paramname=Paramvalue.
HistorySetDupeKey Set duplicate key. EditText contains duplicate key. See RSS#Duplicates.
HistorySetDupeScore Set duplicate score. EditText contains duplicate score. See RSS#Duplicates.
HistorySetDupeMode Set duplicate mode. EditText contains one of SCORE, ALL, FORCE. See RSS#Duplicates.
HistorySetDupeBackup Set use as duplicate backup-flag for history items. EditText contains 0 or 1. See RSS#Duplicates.
HistoryMarkBad Mark history item as bad (and download other duplicate). See RSS#Duplicates.
HistoryMarkBad Mark history item as good. See RSS#Duplicates.
  • Offset - offset for commands FileMoveOffset and GroupMoveOffset. For all other commands must be "0".
  • EditText - additional parameter if mentioned in the command description, otherwise an empty string.
  • IDs - array of IDs (as integers).
    • File-commands (FileXXX) need ID of file.
    • 13.0 In v13 all other commands need NZBID.
    • 13.0 In v12: For group-commands ID of any file in this group can be used, for example field FirstID or LastID of group-structure (LastID is preferred). Post-commands need ID of post-jobs. History-commands need ID of History-items.

Return value: "True" on success or "False" on failure.

Method "scan"

Signature:

bool scan() 

Request rescanning of incoming directory for nzb-files.

Return value: Always "True".

Status, logging and statistics

Method "status"

Signature:

struct status() 

Request for current status (summary) information.

Return value: This method returns a structure with following fields:

Field Type Description
RemainingSizeLo int Remaining size of all entries in download queue, in bytes. This field contains the low 32-bits of 64-bit value
RemainingSizeHi int Remaining size of all entries in download queue, in bytes. This field contains the high 32-bits of 64-bit value
RemainingSizeMB int Remaining size of all entries in download queue, in megabytes.
ForcedSizeLo int 13.0 Remaining size of entries with FORCE priority, in bytes. This field contains the low 32-bits of 64-bit value
ForcedSizeHi int 13.0 Remaining size of entries with FORCE priority, in bytes. This field contains the high 32-bits of 64-bit value
ForcedSizeMB int 13.0 Remaining size of entries with FORCE priority, in megabytes.
DownloadedSizeLo int Amount of data downloaded since server start, in bytes. This field contains the low 32-bits of 64-bit value
DownloadedSizeHi int Amount of data downloaded since server start, in bytes. This field contains the high 32-bits of 64-bit value
DownloadedSizeMB int Amount of data downloaded since server start, in megabytes.
DownloadRate int Current download speed, in Bytes per Second.
AverageDownloadRate int Average download speed since server start, in Bytes per Second.
DownloadLimit int Current download limit, in Bytes per Second. The limit can be changed via method "rate". Be aware of different scales used by the method rate (Kilobytes) and this field (Bytes).
ThreadCount int Number of threads running. It includes all threads, created by the program, not only download-threads.
PostJobCount int Number of Par-Jobs or Post-processing script jobs in the post-processing queue (including current file).
ParJobCount int 12.0 Deprecated, use PostJobCount instead.
UrlCount int Number of URLs in the URL-queue (including current file).
UpTimeSec int Server uptime in seconds.
DownloadTimeSec int Server download time in seconds.
ServerStandBy bool "False" - there are currently downloads running, "True" - no downloads in progress (server paused or all jobs completed).
DownloadPaused bool "True" if download queue is paused via first pause register (soft-pause).
Download2Paused bool 13.0 "True" if download queue is paused via second pause register (manual pause). Deprecated, there is no second pause register in v13.
ServerPaused bool 12.0 Deprecated, use DownloadPaused instead.
PostPaused bool "True" if post-processor queue is currently in paused-state.
ScanPaused bool "True" if the scanning of incoming nzb-directory is currently in paused-state.
ServerTime int Current time on computer running NZBGet. Time is in C/Unix format (number of seconds since 00:00:00 UTC, January 1, 1970).
ResumeTime int Time to resume if set with method "scheduleresume". Time is in C/Unix format.
FeedActive bool "True" if any RSS feed is being fetched right now.
NewsServers array Status of news-servers. See below.

Field NewsServers is an array of structures with following fields:

Field Type Description
ID int Server number in the configuration file. For example "1" for server defined by options "Server1.Host", "Server1.Port", etc.
Active bool True if server is in active state (enabled). Active doesn't mean that the data is being downloaded from the server right now. This only means the server can be used for download (if there are any download jobs).

Method "log"

Signature:

array log(int IDFrom, int NumberOfEntries) 

Request for screen-log. This method is similar to command "nzbget -G <NumberOfEntries>" but returns more information and can return lines from the specified log-ID. This method returns entries from server's screenlog-buffer. The size of this buffer is limited and can be set via option "LogBufferSize" in server's configuration file. Which messages should be saved to screenlog and which should be saved to log-file can be set via server's options InfoTarget, WarningTarget, ErrorTarget and DebugTarget in server's configuration file.

Parameters:

  • IDFrom - The first ID to be returned.
  • NumberOfEntries - Number of entries, which should be returned.

NOTE: only one parameter - either IDFrom or NumberOfEntries - can be specified. The other parameter must be "0".

TIP: If your application stores log-entries between subsequential calls to method log(), the usage of parameter IDFrom is recommended, since it reduces the amount of transferred data.

Return value: This method returns an array of structures with following fields:

Field Type Description
ID int ID of log-entry.
Kind string Class of log-entry, one of the following strings: INFO, WARNING, ERROR, DEBUG.
Time int Time in C/Unix format (number of seconds since 00:00:00 UTC, January 1, 1970).
Text string Log-message.

NOTE: if there are no entries for requested criteria, an empty array is returned.

Method "writelog"

Signature:

bool writelog(string Kind, string Text) 

Append log-entry into server's log.

Parameters:

  • Kind - Kind of log-message. Must be one of the following strings: INFO, WARNING, ERROR, DETAIL, DEBUG. Debug-messages are processed by server, only if it was compiled in debug-mode.
  • Text - Text to be added into log.

Return value: Always "True".

Pause and speed limit

Method "rate"

Signature:

bool rate(int Limit) 

Set download speed limit.

Parameters:

  • Limit - new download speed limit in KBytes/second. Value "0" disables speed throttling.

Return value: "True" on success or "False" on failure.

Method "pausedownload"

Signature:

bool pausedownload() 

Pause download queue on server.

Return value: Always "True".

Method "resumedownload"

Signature:

bool resumedownload() 

Resume (previously paused) download queue on server.

Return value: Always "True".

Method "pausepost"

Signature:

bool pausepost() 

Pause post-processing.

Return value: Always "True".

Method "resumepost"

Signature:

bool resumepost() 

Resume (previously paused) post-processing.

Return value: Always "True".

Method "pausescan"

Signature:

bool pausescan() 

Pause scanning of directory with incoming nzb-files.

Return value: Always "True".

Method "resumescan"

Signature:

bool resumescan() 

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

Return value: Always "True".

Method "scheduleresume"

Signature:

bool scheduleresume(int Seconds) 

Schedule resuming of all activities after expiring of wait interval.

Parameters:

  • Seconds - amount of seconds to wait before resuming.

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

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

Return value: Always "True".

Configuration

Method "config"

Signature:

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 become some options passed via command line.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Option name.
Value string Option value.

Notes:

  • 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 ("/home/user/downloads/dst").

Method "loadconfig"

Signature:

struct[] loadconfig() 

Reads configuration file from the disk.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Option name.
Value string Option value.

Notes:

  • The option value is returned exactly as it is stored in the configuration file. For example it may contain variable references (e. g. "${MainDir}/dst").

Method "saveconfig"

Signature:

bool saveconfig(struct[] options) 

Saves configuration file to the disk.

Parameters:

  • options - array of structs
Field Type Description
Name string Option name.
Value string Option value.

Return value: "True" on success or "False" on failure.

Method "configtemplates"

Signature:

struct[] configtemplates() 

Reads NZBGet configuration file template from disk and extracts configuration sections from all post-processing files. This information is for example used by web-interface to build settings page.

Return value: This method returns an array of structures with following fields:

Field Type Description
Name string Post-processing script name. For example "videosort/VideoSort.py". This field is empty in the first record, which holds the config template of the program itself.
DisplayName string Nice script name ready for displaying. For example "VideoSort".
PostScript bool 13.0 "True" for post-processing scripts.
ScanScript bool 13.0 "True" for scan scripts.
QueueScript bool 13.0 "True" for queue scripts.
SchedulerScript bool 13.0 "True" for scheduler scripts.
Template string Content of the configuration template.

Deprecated

Method "pausedownload2"

13.0 Signature:

bool pausedownload2() 

Pause download queue on server via second pause register.

NOTE: method "pausedownload2" is deprecated in v13, where the second pause was eliminated. In v13 this method is a synonym for "pausedownload".

Options "ParPauseQueue", "PostPauseQueue", "TaskX.Command=PauseDownload" and "TaskX.Command=UnpauseDownload" use the so called first pause-register. To not interfere with the pause-state maintained by these commands the manual pause performed by user should use the second pause register.

Return value: Always "True".

Method "resumedownload2"

13.0 Signature:

bool resumedownload2() 

Resume (previously paused) download queue on server via second pause register.

NOTE: method "resumedownload2" is deprecated in v13, where the second pause was eliminated. In v13 this method is a synonym for "resumedownload".

Return value: Always "True".

Method "urlqueue"

13.0 Signature:

struct[] urlqueue() 

Request for list of items in URL-queue.

NOTE: method "urlqueue" is deprecated in v13, where URLs are put into the same queue with NZB-files and are returned by method "listgroups".

Return value: This method returns an array of structures with following fields:

Field Type Description
ID int ID of URL in the queue.
NZBFilename string Name of nzb-file, if it was passed when the URL was added to queue. May be empty string.
URL string URL to download file from.
Name string The name of nzb-file without path and extension (if it was passed) or a part of the URL. Ready for user-friendly output.
Category string Category assigned to nzb-file when it is added to download queue (after downloading from URL). If the category is empty the category is read from HTTP-response which is usually returned from server hosting the nzb-file.
Priority int Priority assigned to nzb-file when it is added to download queue (after downloading from URL).

Since the nzb-files are usually downloaded from URLs very fast, there are no commands provided to manage the URL-queue (delete, move items).

Method "postqueue"

13.0 Signature:

struct[] postqueue(int NumberOfLogEntries) 

Request for list of items in post-processor-queue.

NOTE: method "postqueue" is deprecated in v13, where the post-processing info is returned by method "listgroups".

Parameters:

  • NumberOfLogEntries - Number of log-entries, saved from post-process-script, which should be returned for the top (currently processing item in post-processor-queue).

Return value: This method returns an array of structures with following fields:

Field Type Description
NZBID int ID of NZB-file.
InfoName string Text with user-friendly formatted name of item. For par-jobs consists of NZBNicename and of ParFilename. For script-jobs is equal to NZBNicename.
NZBFilename string Name of nzb-file, this file was added to queue from. The filename could include fullpath (if client sent it by adding the file to queue).
NZBName string The name of nzb-file without path and extension. Ready for user-friendly output.
NZBNicename string 12.0 Deprecated, use NZBName instead.
DestDir string Destination directory for output file.
ParFilename string Name of main par-file. For script-jobs this field is empty.
Stage string Indicate current stage of post-job. On of the predefined text constants: QUEUED, LOADING_PARS, VERIFYING_SOURCES, REPAIRING, VERIFYING_REPAIRED, EXECUTING_SCRIPT, FINISHED. The last constant (FINISHED) is very unlikely, because the post-jobs is deleted from queue right after it is completed. If nzb-file has no par-files or par-check is disabled the par-stages (LOADING_PARS..VERIFYING_REPAIRED) are skipped. If postprocess-script is not defined in program's options the stage EXECUTING_SCRIPT is skipped.
ProgressLabel string Text with short description of current action in post processor. For example: "Verifying file myfile.rar".
FileProgress int Compeleting of current file. A number in the range 0..1000. Divide it to 10 to get percent-value.
StageProgress int Compeleting of current stage. A number in the range 0..1000. Divide it to 10 to get percent-value.
TotalTimeSec int Number of seconds this post-job is beeing processed (after it first changed the state from QUEUED).
StageTimeSec int Number of seconds the current stage is beeing processed.
Log array Array of structs with log-messages. For description of struct see method log.

NOTE: postprocessor executes only one job at a time - the first (top) job in post-queue. Fields ProgressLabel, FileProgress, StageProgress, TotalTimeSec, StageTimeSec and Log have meaning only for that job.

Method "appendurl"

13.0 Signature:

bool appendurl(string NZBFilename, string Category, int Priority, bool AddToTop, string URL,
      bool AddPaused, string DupeKey, int DupeScore, string DupeMode)

Add URL to download queue.

NOTE: method "appendurl" is deprecated in v13, where URLs can be added by method "append".

Parameters:

  • NZBFilename - name of nzb-file. Server uses the name to build destination directory.
  • Category - category for nzb-file. Can be empty string.
  • Priority - priority for nzb-file. 0 for "normal priority", positive values for high priority and negative values for low priority. Default priorities are: -100 (very low), -50 (low), 0 (normal), 50 (high), 100 (very high).
  • AddToTop - "True" if the file should be added to the top of the URL queue or "False" if to the end.
  • URL - URL of nzb-file. It must be a complete URL starting with "http://". If the program was compiled with TLS/SSL support the protocol "https://" is also supported.
  • AddPaused - "True" if the file should be added in paused state. This parameter is supported since version 12.0.
  • DupeKey - duplicate key for nzb-file. See RSS#Duplicates. This parameter is supported since version 12.0.
  • DupeScore - duplicate score for nzb-file. See RSS#Duplicates. This parameter is supported since version 12.0.
  • DupeMode - duplicate mode for nzb-file. See RSS#Duplicates. This parameter is supported since version 12.0.

NOTE: The command returns immediately after adding the URL to URL-queue before the actual file is downloaded.

Return value: "True" on success or "False" on failure.

Examples

The most comprehensive example on using JSON-RPC with NZBGet is NZBGets built-in web-interface. Look at the javascript sources in directory webui.

Another comprehensive example is NZBGetWeb - old web-interface written in PHP for NZBGet versions prior 9.0. Look in download section for source code. Take into account that this application is not developed anymore and may not be fully compatible with actual NZBGet versions. Still it's a good source for PHP example.

Two following examples show how to interact with NZBGet from Python using XML-RPC.

Adding file to download queue

NOTE: In this example the method append is called with signature from NZBGet 0.6.0, which had less parameters but is still supported.

TODO: Update to signature v13.

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> filename="C:\\ubuntu-7.10.nzb"
>>> in_file = open(filename, "r")
>>> nzbcontent = in_file.read()
>>> in_file.close()
>>> from base64 import standard_b64encode
>>> nzbcontent64=standard_b64encode(nzbcontent)
>>> server.append(filename, 'software', False, nzbcontent64)
True
>>>

Obtaining log

C:\>C:\Programme\Python25\python.exe
Python 2.5.1 (r251:54863, Apr 18 2007, 08:51:08) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from xmlrpclib import ServerProxy
>>> server = ServerProxy('http://nzbget:tegbzn6789@localhost:6789/xmlrpc')
>>> server.log(1, 0)
[{'Text': 'nzbget server-mode', 'Kind': 'INFO', 'ID': 1, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [1/131]', 
'Kind': 'INFO', 'ID': 2, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [2/131]', 
'Kind': 'INFO', 'ID': 3, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [3/131]', 
'Kind': 'INFO', 'ID': 4, 'Time': 1202409509}, 
{'Text': 'Downloading ubuntu-7.10\ubuntu-7.10-desktop-i386.part04.rar [4/131]', 
'Kind': 'INFO', 'ID': 5, 'Time': 1202409509}, 
{'Text': 'Pausing download', 'Kind': 'INFO', 'ID': 6, 'Time': 1202409513}]
>>>
Donation



Get NZBGet at SourceForge.net. Fast, secure and Free Open Source software downloads

Personal tools