Back
Download What's New FAQ Home
Ultra Message API

NZBClient API

NZBClient uses a simple, versioned REST API to receive messages and broadcast them to devices running NZBClient. To simplify the user registration process and usage of our API, there are no complicated out-of-band authentication mechanisms or per-call signing libraries required, such as OAuth. Standard HTTP libraries available in just about every language, or even from the command line, can be used without any custom modules or extra dependencies needed.

NZBClient API is designed to be compatible with Pushover's Message API, so converting existing notification scripts to work with NZBClient in most cases should be as simple as changing the API address from api.pushover.net to api.nzbclient.app.

Push notifications are only supported from NZBClient version 2023.3, and require a subscription to NZBClient Ultra, you can find out more about Ultra here.

TL;DR

  1. Open NZBClient and sign up to Ultra, after you have created an account and subscribed to Ultra you will be given token and user keys to use with the API.

  2. POST an HTTPS request to https://api.nzbclient.net/1/messages.json with the following parameters:

    • token - your application's API token (required)
    • user - your user key (required)
    • message - your message (required)

    Some optional parameters may also be included:

    • title - a string value to be used as your push notification title
    • subtitle - a string value to be used as your push notification subtitle
    • isEncrypted - a bool value, set true and only required when using encryption (documentation)
    • priority - a value of -1, 0 (default), 1 (documentation)
    • sound - the name of a supported sound to override your default sound choice (not supported by the NZBClient as of 2023.3)
    • url - a url used for deep linking into the app eg: nzbclient://downloads?nzbid=1234 (documentation)

That's it. Make sure your application is friendly to our API servers and you're all set. For more information on each parameter, keep reading or jump to a section at the left.

Need help using our API or found an error in the documentation? Drop us a line.

Code Examples

Python

The standard httplib and urllib libraries can be used:

import httplib, urllib
conn = httplib.HTTPSConnection("api.nzbclient.app:443")
conn.request("POST", "/1/messages.json",
  urllib.urlencode({
    "token": "APP_TOKEN",
    "user": "USER_KEY",
    "message": "hello world",
  }), { "Content-type": "application/x-www-form-urlencoded" })
conn.getresponse()

For Python 3, httplib has been replaced with http.client and urlencode has moved to urllib.parse.

import http.client, urllib
conn = http.client.HTTPSConnection("api.nzbclient.app:443")
conn.request("POST", "/1/messages.json",
  urllib.parse.urlencode({
    "token": "APP_TOKEN",
    "user": "USER_KEY",
    "message": "hello world",
  }), { "Content-type": "application/x-www-form-urlencoded" })
conn.getresponse()

Unix command line

The [curl](https://curl.haxx.se/) program may be used from the command line or integrated into shell scripts:

curl -s \
  --form-string "token=APP_TOKEN" \
  --form-string "user=USER_KEY" \
  --form-string "message=hello world" \
  https://api.nzbclient.app/1/messages.json

Ruby

The standard Net::HTTPS library can be used:

require "net/https"

url = URI.parse("https://api.nzbclient.app/1/messages.json")
req = Net::HTTP::Post.new(url.path)
req.set_form_data({
  :token => "APP_TOKEN",
  :user => "USER_KEY",
  :message => "hello world",
})
res = Net::HTTP.new(url.host, url.port)
res.use_ssl = true
res.verify_mode = OpenSSL::SSL::VERIFY_PEER
res.start {|http| http.request(req) }

Encryption

NZBClient supports limited end to end encryption of messages, the message body can be encrypted before sending and decrypted in the app before it's presented, using a private key stored in the app's key-chain, this avoids NZBClient's or Apple's servers reading the message body.

Currently only the message parameter supports encryption as it's expected only the message body will contain private or sensitive information and other fields like title, subtitle will have non-sensitive messages like NZB Downloaded.

If you are sending an encrypted message set isEncrypted to True so the app knows the message needs decrypting.

The private key is a URL-safe base64-encoded 32-byte key, you can create your own and copy it into NZBClient or let the app generate it for you (preferred). This must be kept secret. Anyone with this key is able to create and read messages.

Currently NZBClient only supports Python's Fernet encryption as it's expected to work without users installing additional library's on there system to get push notifications working, if you would like to use an alternative please contact support, I'm happy to make improvements/changes to improve security and privacy.

Python Example

from cryptography.fernet import Fernet
import http.client, urllib

message = "hello world"

encryptedMessage = Fernet(PRIVATE_KEY).encrypt(message.encode())

conn = http.client.HTTPSConnection("api.nzblclient.app:443")
conn.request("POST", "/1/messages.json",
  urllib.parse.urlencode({
    "token": "APP_TOKEN",
    "user": "USER_KEY",
    "message": encryptedMessage,
    "isEncrypted": True,
  }), { "Content-type": "application/x-www-form-urlencoded" })
conn.getresponse()

Message Priority

By default, messages have normal priority (a priority of 0). Messages may be sent with a different priority that affects how the message is presented to the user. Please use your best judgement when sending messages to other users and specifying a message priority.

Low Priority (-1)

Messages with a priority parameter of -1 will be considered low priority and will be sent as an passive interruption level where the system adds the notification to the notification list without lighting up the screen or playing a sound.

Normal Priority (0)

Messages sent without a priority parameter, or sent with the parameter set to 0, will have the default priority. These messages trigger sound, vibration, and display an alert according to the user's device settings.

They will be sent as an active interruption level where the system presents the notification immediately, lights up the screen, and can play a sound.

High Priority (1)

Messages sent with a priority of 1 are high priority messages that bypass a user's quiet hours. These messages will always play a sound and vibrate (if the user's device is configured to) regardless of the delivery time. High-priority should only be used when necessary and appropriate.

They will be sent as an Time Sensitive interruption level where the system presents the notification immediately, lights up the screen, can play a sound, and breaks through system notification controls.

If you are using a Pushover script, 'Lowest Priority' (-2) and 'Emergency Priority' (2) are ignored by NZBClient and set to 'Low Priority' (-1) and 'High Priority' (1) respectively.

URL/Deep Links

NZBClient supports deep links into the app when tapping on a notification the app will attempt to open the correct tab and if available display the NZB details for that notification. Currently only the below links are support.

All deep-links should be prefaced with nzbclient:// all other links will be ignored

Downloads

nzbclient://downloads?nzbid=1234 When provided this link the app will open the Downloads tab, if you provide an nzbid (optional) and the NZB is still in your queue the app will present the details page for this NZB.

History

nzbclient://history?nzbid=1234 When provided this link the app will open the History tab, if you provide an nzbid (optional) and the NZB is still in your history the app will present the details page for this NZB.

Search

nzbclient://search When provided this link the app will open the Search tab.

Files

nzbclient://files When provided this link the app will open the Files tab.

Settings

nzbclient://settings When provided this link the app will open the Settings tab.