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
-
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.
-
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 titlesubtitle
- a string value to be used as your push notification subtitleisEncrypted
- 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.