শেয়ার

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

  1. 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.
  2. 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

ScopeAllows
readevery GET endpoint
monitors:writecreate / change / delete / pause / resume monitors, create and delete maintenance windows
incidents:writeopen manual incidents, post updates, acknowledge
servers:readGET /servers/{id}/metrics and /services
status:writereserved for status page changes in a later version
webhooks:writecreate 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."]}
HTTPcodeWhen
400bad_requestno body / not JSON
401unauthorizedno, unknown, revoked or expired token
402plan_limitthe plan does not allow one more of these
403forbiddenmissing scope or permission
404not_foundunknown endpoint, or the object is not in your organisation
405method_not_allowedwrong method; the Allow header lists the right ones
422validationa field is wrong
429rate_limitedtoo many requests this minute
500server_errorsomething 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:

  • transaction and browser: the start URL in url. A transaction's steps go in config.steps (an array, or the JSON text of one) and its sign-in values in http_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 in url, the port in port (empty = the default port of the type, also read from host:port), the sign-in in http_auth_user / http_auth_pass (encrypted at rest), the other settings in config. 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:

FieldMeaning
kindwebpush (default when endpoint is given), fcm (Android app token) or apns (iOS app token)
endpoint, keys.p256dh, keys.authfor 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
tokenfor fcm / apns: the device token (letters, digits, _ : - ., up to 1000 characters)
nameoptional label; empty = derived from the user agent ("Chrome on Android") or "Android app" / "iOS app"
user_agentoptional; 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:

EventSent when
monitor.downa monitor is confirmed down
monitor.upit recovers
monitor.degradedsome of its locations fail
monitor.ssl_expiryits certificate is inside the warning window
monitor.domain_expiryits domain is inside the warning window
monitor.dns_changedthe DNS answer changed
monitor.content_changedthe page content changed
monitor.createda monitor was created
monitor.deleteda monitor was deleted
server.offlinean agent stopped reporting
server.onlineit reports again
server.alerta 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_clearedone of those is back to normal
server.anomalya server metric is far from its usual values (anomaly)
server.lve_faulta CloudLinux account hit its LVE limits too often
server.backup_faileda JetBackup run or job failed or partially completed
server.k8sKubernetes nodes not Ready, a pod failing or restarting (agent kubectl collector)
monitor.anomalya monitor's response time is far from its usual values (anomaly)
monitor.correlatedrelated monitors are failing together (grouped alert)
monitor.flappinga monitor keeps switching between up and down
incident.openeda manual incident was opened
incident.updatedan update was posted (manual or through the API)
incident.resolvedreserved; 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.

এই পেজটি কি সহায়ক ছিল?

একটি ক্লিক আমাদের এই ডকস উন্নত করতে সাহায্য করে।

এই পেজ শেয়ার করুনসাধারণ লিংক - কোনো ট্র্যাকার নেই, ক্লিক না করা পর্যন্ত কিছু লোড হয় না।