Skip to main content

API Reference

Monitor

Send heartbeat pings from your services, and manage monitors programmatically. Heartbeat pings need no API key — each monitor has a unique URL token. The management endpoints use the secret key or a personal access token and require the Monitor module to be enabled — requests return 403 when it is off.

A personal access token carries its user's Monitor permission: view is needed to read and edit to create, update or delete, and requests return 403 otherwise. Secret key requests are trusted at the account level and are not subject to per-user permissions.

Send Heartbeat

POST /api/v1/monitor/heartbeat/:token URL Token 60 req/min

Records a heartbeat for a monitor, marking it as up. The token is unique per monitor and shown in the monitor settings.

No X-Api-Key header is needed. The monitor token in the URL acts as authentication.

Example

curl -X POST https://squirrelstack.app/api/v1/monitor/heartbeat/your_monitor_token

Success Response

{
  "status": "ok"
}

Error Response

Returns 404 Not Found with an empty body if the token is invalid or the monitor is inactive.

Monitor Object

Monitors are addressed by slug, the same identifier used in the web app's URLs. Heartbeat monitors include their heartbeat_url and the grace_period_seconds allowed after each expected period before a missed heartbeat is logged (10% of the interval, minimum 30 seconds). Both are null for URL checks.

{
  "monitor": {
    "id": 42,
    "slug": "nightly-backup",
    "name": "Nightly Backup",
    "monitor_type": "heartbeat",
    "url": null,
    "interval_seconds": 86400,
    "grace_period_seconds": 8640,
    "heartbeat_url": "https://squirrelstack.app/api/v1/monitor/heartbeat/your_monitor_token",
    "status": "up",
    "last_checked_at": "2026-09-11T02:00:14Z",
    "slack_notifications_enabled": true,
    "slack_channel_id": null,
    "slack_channel_name": null,
    "created_at": "2026-09-01T10:00:00Z",
    "updated_at": "2026-09-11T02:00:14Z"
  }
}

List Monitors

GET /api/v1/monitors Secret Key / PAT 30 req/min

Returns the account's monitors ordered by name. Accepts limit and offset (1–100, default 50) and returns a meta object with the unpaginated total.

Parameters

Parameter Type Required Description
monitor_type string No check or heartbeat
status string No up, down or unknown
limit integer No Number of results, 1–100 (default 50)
offset integer No Number of results to skip (default 0)

Example

curl https://squirrelstack.app/api/v1/monitors?monitor_type=heartbeat \
  -H "X-Api-Key: your_secret_key"

Success Response

{
  "monitors": [ { "id": 42, "slug": "nightly-backup", "name": "Nightly Backup", ... } ],
  "meta": { "total": 3, "limit": 50, "offset": 0 }
}

Get Monitor

GET /api/v1/monitors/:slug Secret Key / PAT 30 req/min

Returns a single monitor together with its 20 most recent check results, newest first.

Success Response

{
  "monitor": {
    "id": 42,
    "slug": "nightly-backup",
    ...,
    "recent_checks": [
      { "id": 9001, "status": "up", "response_time_ms": null, "response_code": null, "checked_at": "2026-09-11T02:00:14Z" },
      { "id": 8990, "status": "missed", "response_time_ms": null, "response_code": null, "checked_at": "2026-09-10T04:24:00Z" }
    ]
  }
}

Check statuses are up, down, or missed (an overdue heartbeat). Returns 404 for a slug that does not belong to the account.

Create Monitor

POST /api/v1/monitors Secret Key / PAT 30 req/min

Creates a monitor. Heartbeat monitors are given a token on creation; the response includes the URL your service should ping.

Parameters

Parameter Type Required Description
name string Yes Human-readable label
monitor_type string Yes check (SquirrelStack requests a URL on a schedule) or heartbeat (your service pings in). Cannot be changed after creation.
url string For checks HTTP or HTTPS URL to request. Ignored for heartbeats.
interval_seconds integer No How often to check, or how often a heartbeat is expected. One of: 60, 300, 900, 1800, 3600, 86400, 604800 (default 300). Heartbeats also accept any whole number of days up to 366, as seconds (e.g. 8208000 for every 95 days).
slack_notifications_enabled boolean No Send Slack alerts on status change (default true)
slack_channel_id string No Slack channel ID to override the account's default channel
slack_channel_name string No Display name for the channel override

Example

curl -X POST https://squirrelstack.app/api/v1/monitors \
  -H "X-Api-Key: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nightly Backup", "monitor_type": "heartbeat", "interval_seconds": 86400}'

Returns 201 Created with the monitor object, or 422 with an errors array when validation fails.

Update Monitor

PATCH /api/v1/monitors/:slug Secret Key / PAT 30 req/min

Updates a monitor. Only the attributes you send are changed; monitor_type and the heartbeat token cannot be changed.

Parameters

Parameter Type Required Description
name string Yes Human-readable label
url string For checks HTTP or HTTPS URL to request. Ignored for heartbeats.
interval_seconds integer No How often to check, or how often a heartbeat is expected. One of: 60, 300, 900, 1800, 3600, 86400, 604800 (default 300). Heartbeats also accept any whole number of days up to 366, as seconds (e.g. 8208000 for every 95 days).
slack_notifications_enabled boolean No Send Slack alerts on status change (default true)
slack_channel_id string No Slack channel ID to override the account's default channel
slack_channel_name string No Display name for the channel override

Example

curl -X PATCH https://squirrelstack.app/api/v1/monitors/nightly-backup \
  -H "X-Api-Key: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"interval_seconds": 604800}'

Returns 200 OK with the updated monitor, 422 when validation fails or no updatable attributes were sent, or 404 for a slug that does not belong to the account.

Delete Monitor

DELETE /api/v1/monitors/:slug Secret Key / PAT 30 req/min

Permanently deletes a monitor and all of its check logs.

Example

curl -X DELETE https://squirrelstack.app/api/v1/monitors/nightly-backup \
  -H "X-Api-Key: your_secret_key"

Returns 204 No Content on success, or 404 for a slug that does not belong to the account.