API
The REST API gives your scripts everything the panel can do with monitors, incidents, servers, status pages, channels, webhooks and maintenance, as JSON over HTTPS. The developer portal at /developers has the short version; this page is the reference.
Base URL: https://your-monitor.example/api/v1
Authentication
- In the panel open API & webhooks → New token. Give it a name, pick its scopes, optionally an expiry date and a rate limit. The token (
aim_…) is shown once; the platform stores only a SHA-256 hash and the first characters. - Send it as a bearer token on every request:
curl https://your-monitor.example/api/v1/me \
-H "Authorization: Bearer aim_YOUR_TOKEN"
A token acts as the user who created it, inside one organisation. It can never do more than that user's role allows: a Viewer's token cannot create monitors whatever its scopes. Revoking a token (panel) takes effect immediately; expired tokens answer 401. Your plan sets how many active tokens an organisation may have.
Scopes
| Scope | Allows |
|---|---|
read | every GET endpoint |
monitors:write | create / change / delete / pause / resume monitors, create and delete maintenance windows |
incidents:write | open manual incidents, post updates, acknowledge |
servers:read | GET /servers/{id}/metrics and /services |
status:write | reserved for status page changes in a later version |
webhooks:write | create and delete outbound webhooks |
A missing scope answers 403 with "code":"forbidden" and "scope":"…".
Rate limits
Each token has a limit of requests per minute (set on the token, otherwise the plan's api_rate_per_min, 60 by default). Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with Retry-After: <seconds> and "code":"rate_limited". Calls and errors are counted per token per day; GET /me and the token list in the panel show them.
Answers and errors
Every answer is JSON. Success:
{"ok": true, "data": {...}}
{"ok": true, "data": [...], "meta": {"page": 1, "per_page": 25, "total": 132}}
Lists accept ?page= and ?per_page= (default 25, max 100; results up to 1000). Errors:
{"ok": false, "error": "Please give the monitor a name.", "code": "validation", "errors": ["Please give the monitor a name."]}
| HTTP | code | When |
|---|---|---|
| 400 | bad_request | no body / not JSON |
| 401 | unauthorized | no, unknown, revoked or expired token |
| 402 | plan_limit | the plan does not allow one more of these |
| 403 | forbidden | missing scope or permission |
| 404 | not_found | unknown endpoint, or the object is not in your organisation |
| 405 | method_not_allowed | wrong method; the Allow header lists the right ones |
| 422 | validation | a field is wrong |
| 429 | rate_limited | too many requests this minute |
| 500 | server_error | something broke on our side (logged) |
Bodies are JSON (Content-Type: application/json); form-encoded bodies work too. Dates are UTC YYYY-MM-DD HH:MM:SS. CORS: any origin may call the API from a browser (preflight OPTIONS answers 204); do not put a token in a page strangers can read.
Endpoints
GET /me
The token, its user, organisation, plan and API usage.
curl $API/me -H "Authorization: Bearer $TOKEN"
{"ok":true,"data":{"token":{"id":3,"name":"Deploy script","prefix":"aim_37a7e6cd","scopes":["read","monitors:write"],"rate_per_min":60,"calls":120,"expires_at":null},
"user":{"id":2,"name":"Jane","email":"jane@example.com","role":"owner"},"org":{"id":2,"name":"Example Ltd","slug":"example-ltd","type":"personal"},
"plan":{"id":3,"name":"Pro","slug":"pro"},"usage":{"today":{"calls":12,"errors":0},"last_30_days":{"calls":120,"errors":2}}}}
GET /monitors
Filters: status (up, down, degraded, pending, paused), type, q (name or URL), group_id. Paginated.
curl "$API/monitors?status=down&per_page=100" -H "Authorization: Bearer $TOKEN"
{"ok":true,"data":[{"id":42,"name":"Shop","type":"http","url":"https://shop.example.com","status":"down","status_since":"2026-11-03 09:12:00","response_time":null,"last_checked":"2026-11-03 09:14:00","last_error":"HTTP 503","interval_sec":60,"timeout_sec":30,"confirmations":2,"locations":["core","eu-de"],"is_active":true,"is_public":false,"maintenance_mode":false,"group_id":null,"ssl_expires_at":"2027-01-10","domain_expires_at":null,"created_at":"2026-10-01 08:00:00"}],"meta":{"page":1,"per_page":100,"total":1}}
POST /monitors
Scope monitors:write. The body takes the same fields as the monitor form; unknown fields are ignored, missing ones get the defaults. Fields: type (http, keyword, api, ping, port, dns, ssl, domain, heartbeat), name, url, method, keyword, keyword_type (present/absent), http_headers (lines), http_auth_user, http_auth_pass, http_body, expected_codes, ssl_check, ssl_warning_days, domain_warning_days, dns_server, expected_ips, heartbeat_interval, port, interval_sec, timeout_sec, confirmations, locations (array or comma list), group_id, notes, is_public, channels (channel ids), tags, and config (object: ignore_ssl, follow_redirects, max_redirects, max_response_ms, expect_headers, detect_changes, case_sensitive, user_agent, bearer, api_key_header, api_key, response_format, json_rules, xpath_rules, body_regex, ping_count, ping_timeout, max_loss_pct, protocol, expect_banner, record_type, match_mode, min_tls, expiry_is_down, grace_sec, alert_degraded). See Monitors for what they mean.
curl -X POST $API/monitors -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type":"api","name":"Orders API","url":"https://api.example.com/health","interval_sec":60,"confirmations":2,
"config":{"response_format":"json","json_rules":"status == ok\nqueue < 100"}}'
Answers 201 with the full monitor (as GET /monitors/{id}). A refused target (private address, bad hostname) answers 422; a plan limit 402.
Types added in 2.1 go through the same validation as the panel form:
transactionandbrowser: the start URL inurl. A transaction's steps go inconfig.steps(an array, or the JSON text of one) and its sign-in values inhttp_auth_user/http_auth_pass, used in the steps as{{username}}/{{password}}. See Synthetic monitoring.mysql,postgres,redis,mongodb,memcached,smtp,imap,pop3,ftp: the host inurl, the port inport(empty = the default port of the type, also read fromhost:port), the sign-in inhttp_auth_user/http_auth_pass(encrypted at rest), the other settings inconfig. See Protocol monitors.
GET /monitors/{id}
The full monitor: everything in the list plus method, keyword, keyword_type, http_headers, http_auth_user, has_http_auth_pass, http_body, expected_codes, ssl_check, ssl_warning_days, domain_warning_days, dns_server, expected_ips, heartbeat_interval, last_heartbeat, port, notes, config (secrets shown as ***), channels, tags, public_url and, for heartbeat monitors, heartbeat_url.
PUT or PATCH /monitors/{id}
Scope monitors:write. Send only the fields to change; config keys are merged into the existing config. An empty http_auth_pass keeps the stored password. is_active: false disables the monitor without deleting it.
curl -X PATCH $API/monitors/42 -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"interval_sec":30,"confirmations":3,"locations":["core","eu-de","us-east"]}'
DELETE /monitors/{id}
Deletes the monitor with its results, incidents and alerts. {"ok":true,"data":{"id":42,"deleted":true}}.
POST /monitors/{id}/pause and /resume
Pause drops queued checks; resume schedules a check at once. Answer: the monitor.
POST /monitors/{id}/test
Runs the check right now from the main server, without storing anything.
{"ok":true,"data":{"monitor_id":42,"status":"up","ms":184,"code":200,"error":"","details":{"final_url":"https://shop.example.com/","ip":"203.0.113.10","timing":{"dns":12,"connect":35,"tls":80,"ttfb":170,"total":184},"size":48213,"redirects":0,"server":"nginx","content_type":"text/html; charset=utf-8"},"location":"core","checked_at":"2026-11-03 09:20:11"}}
GET /monitors/{id}/results
Raw results, newest first. ?hours= (default 24, max 168), ?location=, ?status=up|down, paginated (per_page up to 1000). Each row: id, location, status, ms, code, error, checked_at.
GET /monitors/{id}/uptime
curl "$API/monitors/42/uptime?days=30" -H "Authorization: Bearer $TOKEN"
{"ok":true,"data":{"monitor_id":42,"status":"up","uptime":{"24h":99.653,"7d":99.95,"30d":99.98,"90d":99.97,"365d":null},"current_uptime_sec":5120,
"daily":[{"date":"2026-10-05","uptime":100,"checks":1440,"avg_ms":180,"downtime_sec":0}, ...]}}
days 1–365 (default 30). null means nothing was measured.
GET /monitors/{id}/response
?hours= (1–168) and optional ?location=. Answers stats (avg, min, max, n over the period), series (up to 200 buckets of t, ms, status, n) and locations (per location over 24 h: checks, average ms, downs, last status, last time).
GET /incidents
Filters: status, resolved (0/1), monitor_id, server_id, severity, q. Paginated, open incidents first. Rows carry id, title, status, severity, kind, monitor_id, monitor_name, server_id, is_manual, is_resolved, started_at, ended_at, duration, error_message, cause, acknowledged_by, acknowledged_at, escalated_at, created_by.
GET /incidents/{id}
The incident plus updates (id, status, message, is_public, user_id, created_at), oldest first.
POST /incidents
Scope incidents:write. Body: title (required), severity (minor, major, critical), status (investigating, identified, monitoring), message (first update), monitor_id / server_id (optional, must be yours), cause, started_at (optional, UTC), public (default true).
curl -X POST $API/incidents -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"title":"Payment provider degraded","severity":"minor","message":"Card payments are slow; we are in contact with the provider."}'
Answers 201 with the incident and its updates and sends the incident.opened webhook event.
POST /incidents/{id}/updates
Scope incidents:write. Body: status (investigating, identified, monitoring, resolved), message (required), public (default true). resolved closes the incident with its duration. Public updates reach status-page subscribers; every update sends incident.updated.
POST /incidents/{id}/acknowledge
Scope incidents:write. Records you as the acknowledger (once) and stops escalation.
GET /alerts
Alert history, newest first. Filters: event, monitor_id, server_id, severity, open=1 (not yet resolved). Rows: id, event, severity, title, message, monitor_id, server_id, incident_id, created_at, resolved_at.
GET /servers
Filters: status (pending, online, offline, paused), q. Rows: id, name, hostname, ip, os, os_family, status, status_since, last_heartbeat, agent_version, location, provider, server_type, group_name, tags, cpu_cores, mem_total, last_metrics (cpu, mem, disk, load1, net_in, net_out, procs, uptime, at), created_at.
GET /servers/{id}
Adds kernel, arch, cpu_model, agent_interval, boot_time, watch_services and thresholds.
GET /servers/{id}/metrics
Scope servers:read. ?hours= 1–720 (default 24). Up to 48 hours the raw samples are bucketed (about 240 points): t, cpu, mem, disk, load1, net_in, net_out, swap_used, disk_read, disk_write; over 48 hours the hourly roll-up (cpu, mem, disk, load1, net_in, net_out). latest repeats the newest sample.
GET /servers/{id}/services
Scope servers:read. The watched services, Docker containers and disks: kind, name, status, detail, changed_at, updated_at.
GET /status-pages and /status-pages/{id}
The list carries id, name, slug, url, visibility, custom_domain, display switches, history_days, allow_subscribe, is_active. One page adds components (id, name, group, description, status operational/degraded/down/maintenance/unknown, monitor_id, server_id), overall, maintenance (active and upcoming windows) and subscribers (verified count).
GET /channels
Your alert channels without their secrets: id, name, type, target (e-mail address, phone, chat <id>, or the webhook host with the path hidden), events, is_default, is_escalation, cooldown_sec, quiet_from, quiet_to, is_active, last_sent_at.
GET /webhooks
Outbound webhooks: id, name, url, events, has_secret, is_active, failures, last_status, last_at. meta.events lists every event with its description.
POST /webhooks
Scope webhooks:write. Body: name, url (http(s), checked by the SSRF guard), events (array or comma list; empty or * = all), secret (optional: when omitted one is generated and returned once as secret), is_active.
curl -X POST $API/webhooks -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Ops bot","url":"https://ops.example.com/aim","events":["monitor.down","monitor.up","incident.updated"]}'
DELETE /webhooks/{id}
Removes the webhook and its delivery log.
GET /maintenance and POST /maintenance
List (paginated; each window carries active) and create (scope monitors:write, permission manage alert channels). Body: name, starts_at, ends_at (UTC, any parseable date), recurrence (once, daily, weekly, monthly), monitor_ids, server_ids, all_monitors, show_on_status, status_page_ids, description. DELETE /maintenance/{id} removes one.
curl -X POST $API/maintenance -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Weekly DB vacuum","starts_at":"2026-11-08 02:00:00","ends_at":"2026-11-08 02:30:00","recurrence":"weekly","monitor_ids":[42,43]}'
GET /locations
The main server (core) and every public probe: code, name, region, country, city, status, is_core; meta.max_locations is your plan's limit.
GET /plans
The public plans with prices, features and limits (-1 = unlimited).
GET /org/usage
Your organisation, plan and subscription, what is used (monitors, servers, channels, members, status pages, API tokens), the plan limits, the dashboard overview (up/down/degraded counts, servers online, open incidents, 30-day uptime) and API calls over the last 30 days.
GET /me/summary
The small status summary a phone widget or a home-screen app shows, for the token's organisation. Scope read.
curl $API/me/summary -H "Authorization: Bearer $TOKEN"
{"ok":true,"data":{"org":{"id":2,"name":"Example Ltd"},"state":"down",
"monitors":{"total":24,"up":22,"down":1,"degraded":1,"paused":0,"pending":0},
"servers":{"total":3,"online":3,"offline":0},"incidents_open":1,"uptime_30d":99.95,"avg_response_ms":212,
"problems":[{"id":42,"name":"Shop","url":"https://shop.example.com","status":"down","since":"2026-11-03 09:12:00","error":"HTTP 503","link":"https://your-monitor.example/app/monitors/42"}],
"unread_notifications":3,"dashboard":"https://your-monitor.example/app","generated_at":"2026-11-03T09:20:11+00:00"}}
state is down when a monitor is down or an incident is open, else degraded when a monitor is degraded, else up, or empty when there are no monitors. problems lists up to 10 active monitors that are down or degraded, oldest first. unread_notifications counts the token user's unread in-app notifications.
GET /devices
The push devices of the token's user (browsers with Web Push, and app tokens). Scope read — a token only ever sees and changes its own user's devices.
{"ok":true,"data":[{"id":7,"kind":"webpush","name":"Chrome on Android","platform":"web","active":true,"endpoint_host":"fcm.googleapis.com",
"user_agent":"Mozilla/5.0 …","created_at":"2026-11-03 08:00:00","last_ok_at":"2026-11-03 09:12:04","failures":0,"last_error":""}],
"meta":{"total":1,"vapid_public_key":"BNc…"}}
The push keys are never returned. meta.vapid_public_key is the key a browser or app needs to subscribe (the applicationServerKey).
POST /devices
Registers (or refreshes) a device for the token's user. Scope read. Body:
| Field | Meaning |
|---|---|
kind | webpush (default when endpoint is given), fcm (Android app token) or apns (iOS app token) |
endpoint, keys.p256dh, keys.auth | for webpush: the browser's PushSubscription as JSON (p256dh and auth may also be sent at the top level). The endpoint must be an https URL that passes the SSRF guard |
token | for fcm / apns: the device token (letters, digits, _ : - ., up to 1000 characters) |
name | optional label; empty = derived from the user agent ("Chrome on Android") or "Android app" / "iOS app" |
user_agent | optional; defaults to the request's User-Agent |
curl -X POST $API/devices -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"kind":"webpush","name":"Office laptop","endpoint":"https://fcm.googleapis.com/fcm/send/…","keys":{"p256dh":"BOr…","auth":"k3…"}}'
Answers 201 with the device (as in the list) when it is new, 200 when the same endpoint or token was already registered (it is then moved to this user). A bad subscription answers 422. A user keeps at most the number of devices the administrator allows (20 by default); registering one more removes the device that has gone longest without a successful delivery. App tokens (fcm, apns) are stored, but this version sends nothing to them: the apps receive alerts through Web Push. See Mobile app and push.
DELETE /devices/{id}
Removes one of the token user's devices: {"ok":true,"data":{"id":7,"deleted":true}}. Another user's device answers 404.
Webhooks
Outbound webhooks (panel: API & webhooks → Webhooks, or the endpoints above) receive a JSON POST for each subscribed event:
{"id":"0b1f…","event":"monitor.down","created_at":"2026-11-03T09:12:00+00:00","org_id":2,
"data":{"monitor":{"id":42,"name":"Shop","type":"http","url":"https://shop.example.com","status":"down","response_time":null,"last_checked":"2026-11-03 09:12:00"},
"incident":{"id":77,"started_at":"2026-11-03 09:12:00","duration":null},"reason":"HTTP 503","locations":{"down_from":["core","eu-de"],"up_from":[]}}}
Headers: Content-Type: application/json, User-Agent: AllInOneMonitor/<version>, X-AIM-Event, X-AIM-Delivery (the delivery id), and when the webhook has a secret X-AIM-Timestamp (Unix seconds) and X-AIM-Signature.
Signature: sha256= + hex HMAC-SHA256 of "<timestamp>.<raw body>" with the secret. Verify it before trusting the payload and reject timestamps older than a few minutes.
PHP:
<?php
$secret = 'your webhook secret';
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_AIM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_AIM_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
http_response_code(401);
exit('bad signature');
}
$event = json_decode($body, true);
// $event['event'], $event['data'] ...
http_response_code(200);
Node:
import crypto from 'node:crypto';
export function verify(headers, rawBody, secret) {
const ts = headers['x-aim-timestamp'];
const sig = headers['x-aim-signature'] || '';
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
return fresh && sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
Answer with any 2xx status within 15 seconds. Other answers and timeouts are retried with growing delays (1, 4, 9, 16 minutes; 5 attempts); the delivery log shows every attempt with the response. After 50 consecutive failures the webhook is switched off until you re-enable it.
Events:
| Event | Sent when |
|---|---|
monitor.down | a monitor is confirmed down |
monitor.up | it recovers |
monitor.degraded | some of its locations fail |
monitor.ssl_expiry | its certificate is inside the warning window |
monitor.domain_expiry | its domain is inside the warning window |
monitor.dns_changed | the DNS answer changed |
monitor.content_changed | the page content changed |
monitor.created | a monitor was created |
monitor.deleted | a monitor was deleted |
server.offline | an agent stopped reporting |
server.online | it reports again |
server.alert | a resource threshold (CPU, memory, disk, inodes, swap, load, temperature), or a database, web, PHP-FPM or mail-queue alert of the 2.1 collectors |
server.alert_cleared | one of those is back to normal |
server.anomaly | a server metric is far from its usual values (anomaly) |
server.lve_fault | a CloudLinux account hit its LVE limits too often |
server.backup_failed | a JetBackup run or job failed or partially completed |
server.k8s | Kubernetes nodes not Ready, a pod failing or restarting (agent kubectl collector) |
monitor.anomaly | a monitor's response time is far from its usual values (anomaly) |
monitor.correlated | related monitors are failing together (grouped alert) |
monitor.flapping | a monitor keeps switching between up and down |
incident.opened | a manual incident was opened |
incident.updated | an update was posted (manual or through the API) |
incident.resolved | reserved; resolutions arrive as incident.updated with status resolved and as monitor.up |
Server alerts for RAID, SMART, reboots and watched services / containers / disks are sent as server.raid, server.smart, server.reboot, server.service_down and server.service_up. These names are not in the event list a webhook can pick, so only webhooks subscribed to all events (* or empty) receive them. See Intelligence for anomalies, correlation and flapping.
Webhooks are sent even during maintenance windows (they are your own code; the suppression applies to alert channels).
Legacy endpoints
Installations upgraded from the old monitor script keep api/status.php (the public JSON of a public monitor by token), public/monitor.php, public/embed.php and public/heartbeat.php; they call the same functions as the new addresses.
One click helps us improve these docs.

