Skip to content

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

POST/add/device

Creates 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

GET/device/count

Returns 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

{
    "success": {
        "devices": 2
    }
}

List devices

GET/device/list

Lists 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

GET/device/status

Returns 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:

{
    "device_id": 751659085216623,
    "device_token": "9f2c4e7a1b3d5f60718293a4"
}

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

POST/update/device

Pushes 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

{
    "success": "updated"
}

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

GETPOST/device/history

Returns 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

POST/edit/device

Changes 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:

device_id=751659085216623&device_name=Web server&update_period=120&notification_users=[]

Response

{
    "success": "Device updated successfully"
}

Fails with Device not found or access denied, Invalid device_details JSON, Invalid notification_config JSON or Validation error in notification_users: ....

Delete device

POST/delete/device

Deletes 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:

device_id=751659085216623&device_token=9f2c4e7a1b3d5f60718293a4

Response

{
    "success": "Device deleted"
}

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

POST/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/enable
  • https://spoilerinterface.com/interface/notifications/device/alerts/disable
  • https://spoilerinterface.com/interface/notifications/device/whatsapp/enable
  • https://spoilerinterface.com/interface/notifications/device/whatsapp/disable
  • https://spoilerinterface.com/interface/notifications/device/sms/enable
  • https://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):

{
    "device_id": 751659085216623,
    "device_token": "9f2c4e7a1b3d5f60718293a4"
}

Response

{
    "success": "success"
}

The change is logged in the notification history (e.g. Notifications disabled). See Notifications for details and error messages.