Ping (network monitor) information¶
A ping device (network monitor) watches a host instead of receiving pushed values. The server checks the host with the chosen monitoring_type (ping, http, https, tcp, ssh, dns or cert_expiry) and records the result. The API calls these devices device. See API usage information for authentication and the response envelope.
Add device¶
/add/deviceCreates a new network monitor for the logged-in user and returns its id and token.
Request¶
Auth: api_key (query param or cookie) · Content-type: application/x-www-form-urlencoded
Request body:
Send the fields as form data.
| Field name | Description | Type |
|---|---|---|
device_name |
Name of the monitor | str |
device_type |
Required by the form, but ignored: the stored type is always device |
str |
host_address |
Host name, IP address or URL to check | str |
update_period |
Check period | int |
monitoring_type |
One of ping, http, https, tcp, ssh, dns, cert_expiry (case-insensitive) |
str |
port |
[Optional] Custom port, e.g. 8443 or 2222 |
int |
device_status |
[Optional] Initial status. Default Offline |
str |
device_token |
[Optional] Device token. Generated when omitted | str |
device_details |
[Optional] JSON string with check options, e.g. {"expected_status_codes": [200]} for http/https. Default {} |
json |
notification_enabled |
[Optional] Status notifications. Default true |
bool |
email_enabled |
[Optional] Email channel. Default false |
bool |
telegram_enabled |
[Optional] Telegram channel. Default false |
bool |
slack_enabled |
[Optional] Slack channel. Default false |
bool |
discord_enabled |
[Optional] Discord channel. Default false |
bool |
msteams_enabled |
[Optional] Microsoft Teams channel. Default false |
bool |
pushbullet_enabled |
[Optional] Pushbullet channel. Default false |
bool |
pushover_enabled |
[Optional] Pushover channel. Default false |
bool |
webhook_enabled |
[Optional] Webhook channel. Default false |
bool |
custom_webhook_enabled |
[Optional] Custom webhook channel. Default false |
bool |
whatsapp_enabled |
[Optional] WhatsApp channel. Default false |
bool |
sms_enabled |
[Optional] SMS channel. Default false |
bool |
notification_config |
[Optional] JSON string with advanced settings, e.g. {"apprise_urls": ["..."]} |
json |
Request example:
https://spoilerinterface.com/interface/add/device?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
Form data:
device_name=Web server&device_type=device&host_address=example.com&monitoring_type=https&update_period=60&email_enabled=true
Response¶
{
"success": {
"device_id": 751659085216623,
"device_token": "9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
"host_address": "example.com"
}
}
Field description¶
| Field name | Description | Type |
|---|---|---|
device_id |
Generated device id | int |
device_token |
The supplied token, or a generated 100-character hex token | str |
host_address |
Host that will be checked | str |
Fails with Invalid monitoring_type. ..., device_details must be valid JSON, notification_config must be valid JSON, or Maximum number of devices reached. Please upgrade your account.
Device count¶
/device/countReturns the number of network monitors owned by the user.
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/device/count?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
Response¶
List devices¶
/device/listLists every network monitor owned by the user. Each host is checked live while the request runs, so the response can take several seconds.
Request¶
Auth: api_key (query param or cookie)
Request body:
None
Request example:
https://spoilerinterface.com/interface/device/list?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
Response¶
{
"success": [
{
"device_id": 751659085216623,
"device_name": "Web server",
"device_type": "device",
"device_status": "Online",
"host_address": "example.com",
"port": null,
"monitoring_type": "https",
"device_details": {},
"alarms": [],
"update_period": 60,
"last_modified": 1763025300,
"actual_update_time": 1763025300,
"device_token": "9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
"notification_enabled": true,
"notification_sent": false,
"last_notification_status": null,
"notification_users": [],
"whatsapp_enabled": false,
"sms_enabled": false,
"notifications": {
"email": true,
"telegram": false,
"slack": false,
"discord": false,
"msteams": false,
"pushbullet": false,
"pushover": false,
"webhook": false,
"custom_webhook": false,
"whatsapp": false,
"sms": false,
"apprise_urls": []
},
"response_time_ms": 84,
"last_check_message": "HTTP 200"
}
]
}
Field description¶
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_name |
Device name | str |
device_type |
Always device for monitors created through /add/device |
str |
device_status |
Result of the live check: Online, Offline or Unknown |
str |
host_address |
Host that is checked | str |
port |
Custom port (null when not set) |
int |
monitoring_type |
Check type | str |
device_details |
Check options | json |
alarms |
Alarms configured for the device | arr |
update_period |
Check period | int |
last_modified |
Last update time plus the account's time_offset converted to milliseconds |
int |
actual_update_time |
Last update time as stored | int |
device_token |
Device token | str |
notification_enabled |
Status notifications enabled, as stored | bool |
notification_sent |
A notification was sent for the current status | bool |
last_notification_status |
Status of the last notification | str |
notification_users |
Extra notification recipients (see Edit device) | arr |
whatsapp_enabled |
WhatsApp channel enabled | bool |
sms_enabled |
SMS channel enabled | bool |
notifications |
All channel flags plus apprise_urls from notification_config |
json |
response_time_ms |
Latency of the live check (null when unavailable) |
int |
last_check_message |
Message from the live check, e.g. HTTP 200 or No ping response |
str |
Device status¶
/device/statusReturns the status of a single network monitor. Authenticated with the device id and token.
Request¶
Auth: Device id + token (no api_key) · Content-type: application/json (only when sending a JSON body)
Request body:
Send as query parameters or a JSON body.
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_token |
Device token | str |
Request example:
Params:
https://spoilerinterface.com/interface/device/status?device_id=751659085216623&device_token=9f2c4e7a1b3d5f60718293a4
JSON body:
Response¶
{
"success": {
"device_id": 751659085216623,
"device_status": "Online",
"host_address": "example.com",
"device_details": {},
"update_period": 60,
"notification_enabled": true,
"alarms": []
}
}
Field description¶
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_status |
Result of a live ICMP ping of host_address (whatever the monitoring_type): Online, Offline or Unknown |
str |
host_address |
Host that is checked | str |
device_details |
Check options | json |
update_period |
Check period | int |
notification_enabled |
Status notifications enabled (null is reported as true) |
bool |
alarms |
Alarms configured for the device | arr |
Update device¶
/update/devicePushes a value for a network monitor.
Request¶
Auth: Device id + token (no api_key) · Content-type: application/json
Request body:
Send a JSON body (required; query parameters are not read).
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_token |
Device token | str |
device_value |
Value to record | float |
device_details |
[Optional] JSON object as a string. Default {} |
json |
epoch_time |
[Optional] Update time. Default: current server time in milliseconds | int |
Request example:
{
"device_id": 751659085216623,
"device_token": "9f2c4e7a1b3d5f60718293a4",
"device_value": 1,
"device_details": "{}"
}
Response¶
Fails with Missing required fields, Invalid device_id or device_value, device_details must be valid JSON or Device not found or invalid token. There is no account-tier rate limit on this endpoint.
Note: the current server code writes fields that the device history table does not have, so this endpoint currently returns {"failed": "Update failed: ..."}. Status checks are done by the server, so monitors do not need to call it.
Device history¶
/device/historyReturns the recorded check results of the user's network monitors, oldest record first.
Request¶
Auth: api_key (query param or cookie) · Content-type: application/json (only when sending a JSON body)
Request body:
Send the filters as a JSON body (optional for this endpoint). device_id, limit and offset may also be sent as query parameters, but min_epoch_tm_sec and max_epoch_tm_sec are only read from the JSON body.
| Field name | Description | Type |
|---|---|---|
min_epoch_tm_sec |
[Optional] Start of the window, compared with checked_at. Default: now minus 2 days (172800 s) |
float |
max_epoch_tm_sec |
[Optional] End of the window. Default: now | float |
device_id |
[Optional] Return only this device. Default: all of the user's devices | int |
limit |
[Optional] Maximum records per device. Default and maximum: 20000 | int |
offset |
[Optional] Records to skip per device (for paging). Default: 0 | int |
Request example:
https://spoilerinterface.com/interface/device/history?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
JSON body:
{
"min_epoch_tm_sec": 1762992000,
"max_epoch_tm_sec": 1763078400,
"device_id": 751659085216623,
"limit": 1000,
"offset": 0
}
Response¶
{
"success": [
{
"device_id": 751659085216623,
"device_name": "Web server",
"monitoring_type": "https",
"min_time": 1762992000,
"max_time": 1763078400,
"data": [
{
"checked_at": 1763025300,
"datetime": "2026-11-13 09:15:00",
"status": "Online",
"response_time_ms": 84,
"message": "HTTP 200",
"monitoring_type": "https"
}
]
}
]
}
Field description¶
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_name |
Device name | str |
monitoring_type |
Current check type of the device | str |
min_time |
Start of the requested window | int |
max_time |
End of the requested window | int |
data |
Check results in the window | arr |
has_more |
Present (true) when limit records were returned or newer records exist after max_epoch_tm_sec |
bool |
Each data item:
| Field name | Description | Type |
|---|---|---|
checked_at |
Check time as stored | int |
datetime |
Check time as YYYY-MM-DD HH:MM:SS, shifted by the account's time_offset |
str |
status |
Check result | str |
response_time_ms |
Latency (0 when unknown) |
int |
message |
Check message (empty string when none) | str |
monitoring_type |
Check type used | str |
Fails with Invalid device_id or device_token when the device does not exist, and Permission denied when it belongs to another user. A user without devices gets {"success": []}.
Edit device¶
/edit/deviceChanges the settings of a network monitor owned by the user. Only the fields sent are changed.
Request¶
Auth: api_key (query param or cookie) · Content-type: application/x-www-form-urlencoded
Request body:
Send the fields as form data.
| Field name | Description | Type |
|---|---|---|
device_id |
Device id (must belong to the user) | int |
device_name |
[Optional] New name | str |
device_token |
[Optional] New token | str |
host_address |
[Optional] New host | str |
update_period |
[Optional] New check period | int |
monitoring_type |
[Optional] New check type (not validated on edit) | str |
device_details |
[Optional] New check options as a JSON string | json |
notification_enabled |
[Optional] Status notifications | bool |
email_enabled, telegram_enabled, slack_enabled, discord_enabled, msteams_enabled, pushbullet_enabled, pushover_enabled, webhook_enabled, custom_webhook_enabled, whatsapp_enabled, sms_enabled |
[Optional] Channel flags | bool |
notification_config |
[Optional] Advanced settings as a JSON string, e.g. {"apprise_urls": ["..."]} |
json |
notification_users |
JSON string holding an array of extra notification recipients. Each item: email (required), name, status_alerts, threshold_alerts, sms_alerts, whatsapp_alerts (booleans) and mobile_number (required, + and country code, when sms_alerts or whatsapp_alerts is true). Currently required: when it is omitted the request fails with Edit failed: .... Send [] to clear the list |
json |
port cannot be changed through this endpoint.
Request example:
https://spoilerinterface.com/interface/edit/device?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
Form data:
Response¶
Fails with Device not found or access denied, Invalid device_details JSON, Invalid notification_config JSON or Validation error in notification_users: ....
Delete device¶
/delete/deviceDeletes a network monitor.
Request¶
Auth: api_key (query param or cookie) · Content-type: application/x-www-form-urlencoded
Request body:
Send the fields as form data.
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_token |
Device token | str |
Request example:
https://spoilerinterface.com/interface/delete/device?api_key=3b9e1f0c7a5d4e2f8a6b0c1d
Form data:
Response¶
Fails with Device not found or access denied when the id and token do not match a device owned by the user. Check history records are not deleted.
Notification settings¶
/notifications/{device_type}/{alert_type}/{action}Enables or disables email, WhatsApp or SMS notifications for one network monitor.
Request¶
Auth: api_key (query param or cookie) and device id + token · Content-type: application/json (only when sending a JSON body)
Request body:
device_type is device or ping. alert_type is alerts (status notifications, notification_enabled), whatsapp (whatsapp_enabled) or sms (sms_enabled). action is enable or disable.
Send the device credentials as query parameters or a JSON body.
| Field name | Description | Type |
|---|---|---|
device_id |
Device id | int |
device_token |
Device token | str |
URLs for this device type:
https://spoilerinterface.com/interface/notifications/device/alerts/enablehttps://spoilerinterface.com/interface/notifications/device/alerts/disablehttps://spoilerinterface.com/interface/notifications/device/whatsapp/enablehttps://spoilerinterface.com/interface/notifications/device/whatsapp/disablehttps://spoilerinterface.com/interface/notifications/device/sms/enablehttps://spoilerinterface.com/interface/notifications/device/sms/disable
Request example:
https://spoilerinterface.com/interface/notifications/device/alerts/disable?api_key=3b9e1f0c7a5d4e2f8a6b0c1d&device_id=751659085216623&device_token=9f2c4e7a1b3d5f60718293a4
JSON body (with ?api_key= in the URL or the cookie):
Response¶
The change is logged in the notification history (e.g. Notifications disabled). See Notifications for details and error messages.