REST API

The REST API gives scripts and other tools access to your team's servers, monitors, heartbeats, alerts and incidents. Use it to build dashboards, sync with a ticketing system, or acknowledge alerts from a chat bot.

Authentication#

Owners and admins create tokens in the API tokens section of the team settings:

• Name: so you can recognise it later, for example "Grafana".
• Access: Read only, or Read and act (also lets the token acknowledge and resolve alerts).
• Expires: after 30, 90 or 365 days, or never.

The token is shown once, so copy it somewhere safe. It only sees that team's data. The list shows who created each token and when it was last used. Revoke it any time from the same page.

A token acts as the person who created it. If they become a Viewer, it can no longer acknowledge or resolve alerts. If they leave the team, their tokens are deleted. Actions taken through the API aren't recorded in the team activity log.

Send it as a bearer token with every request:

curl https://alertly.net/api/v1/servers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Base URL and format#

• Base URL: https://alertly.net/api/v1
• Responses are JSON. Lists are wrapped in data, with links and meta for pagination (50 items a page, use ?page=2).
• Dates are ISO 8601 with a timezone.

Rate limits#

Each token can make 120 requests a minute. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining, so you can slow down before you hit the limit. Above it you get 429 Too Many Requests. Wait for the number of seconds in the Retry-After header.

Endpoints#

Acknowledging and resolving are safe to repeat: if the alert is already acknowledged or resolved, you get it back unchanged. Resolving by hand doesn't send a recovery notification, and if the problem is still there, the next check opens a new alert.

Fields#

• Server: id, name, status, hostname, ip_address (IPv4), ipv6_address, os, os_version, kernel, arch, agent_version, cpu_cores, cpu_model, memory_total_bytes, uptime_seconds, heartbeat_interval, last_seen_at, created_at.
• Monitor: id, name, type (http, tcp, ping or dns), status, url, host, port, interval_seconds, last_checked_at, last_response_time_ms, last_status_code, last_error, ssl_expires_at, domain_expires_at, status_changed_at, created_at.
• Heartbeat: id, name, status, period_seconds, cron_expression, timezone, grace_seconds, due_at, last_ping_at, last_duration_ms, status_changed_at, created_at. Ping URLs aren't returned, because anyone with one can mark the job as healthy.
• Incident: id, title, status (investigating, identified, monitoring or resolved), severity, is_public, assignee ({ "id", "name" } or null), started_at, resolved_at. GET /incidents/{id} adds updates, each with status, body and created_at.

Example: an alert#

{
  "data": {
    "id": 42,
    "type": "threshold",
    "severity": "critical",
    "status": "triggered",
    "title": "Disk almost full on web-01",
    "message": "Disk usage is 96% (threshold 95%).",
    "value": 96.2,
    "server_id": 7,
    "monitor_id": null,
    "heartbeat_id": null,
    "incident_id": null,
    "triggered_at": "2026-10-11T09:30:00+00:00",
    "acknowledged_at": null,
    "acknowledged_by": null,
    "resolved_at": null
  }
}

acknowledged_by is { "id": 3, "name": "Sam" } once someone has acknowledged the alert, otherwise null.

Example: acknowledge from a script#

curl -X POST https://alertly.net/api/v1/alerts/42/acknowledge \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Errors#

Error responses include a message field explaining what went wrong.