25 endpoints. Send your API key as Authorization: Bearer <key> on each request; see The API and AI assistants for keys, errors, idempotency and the conventions every endpoint shares.
GET /api/monitors
The organisation's monitors (404 unless the server has MONITORS=on)
Responses:
| Status | Meaning |
|---|---|
| 200 | limit, interval_choices, authorisation_text and monitors (state: waiting_for_probe, waiting_for_ping, up, degraded, cert_expiring, checking, down, maintenance, paused or plan_limit) |
| 404 | Monitors are not switched on |
POST /api/monitors
Add a monitor (members and above, signed in as a person). Stored only; nothing is checked until the probe exists.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 100 characters. |
type | string | No | heartbeat: a job that checks in. It needs name and interval_seconds (60, 300, 900, 3600, 21600, 86400 or 604800), optional grace_seconds and project_id, no target and no authorised; the response holds ping_url ONCE. One of: http, heartbeat. Default "http". |
target | string | Yes | A public http or https address. Private, loopback, link-local, metadata and internal names are refused. Do not put a password, token or other secret in a monitored address. |
interval_seconds | integer | No | Not faster than the plan allows; default is the plan's own interval. One of: 60, 300, 600, 900, 1800, 3600. |
timeout_ms | integer | No | From 1000 to 30000. |
expected_status | integer or null | No | null: any status below 400. From 100 to 599. |
degraded_ms | integer or null | No | From 50 to 60000. |
failure_threshold | integer or null | No | Failed checks in a row before an incident opens (null or left out: 2). With two or more probes, two probes must also agree. Also accepted when changing a web or Coolify monitor; a monitor shows the number in use. From 1 to 10. |
cert_warn_days | integer or null | No | Days before the certificate runs out to start warning (null or left out: 30). The first warning is at this many days, then at 14 and 7 days left when they are below it; inside it the monitor shows cert_expiring. Also accepted when changing a web monitor (null sets it back to 30); a web monitor shows the number in use. From 1 to 365. |
keyword | string or null | No | A word or phrase the page must contain or must not contain (see keyword_mode). The probe reads at most 256 KiB, judges it in memory and keeps only pass or fail. Not a secret: it is sent to every probe. Up to 200 characters. |
keyword_mode | string or null | No | present (default when a keyword is given) or absent. One of: present, absent, null. |
header_name | string or null | No | A response header that must be present (letters, digits, hyphens). Plain setting, sent to every probe. Up to 100 characters. |
header_value | string or null | No | If set, the header must equal it (ignoring case). Needs header_name. Up to 200 characters. |
json_path | string or null | No | A dotted path into the JSON reply, like data.items.0.name. Comes with json_expected. Up to 200 characters. |
json_expected | string or null | No | The value at json_path, compared as text (true, 3, ok). Objects and arrays never match. Up to 200 characters. |
project_id | integer or null | No | |
public_name | string or null | No | A suggested public name for status pages (a suggestion only: nothing is public until an admin saves the monitor as a component). When a component is saved without a name, this is the name used. Never filled in from the monitor's name. Up to 100 characters. |
authorised | boolean | Yes | The statement that you own the site or are authorised to test it (the text is in the list response) Must be true. |
Responses:
| Status | Meaning |
|---|---|
| 201 | The monitor |
| 400 | Validation failed |
| 402 | The plan's monitor limit is reached |
GET /api/incidents
The organisation's incidents, newest first, with their monitors and updates (404 unless MONITORS=on)
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | No | Default 50. From 1 to 200. |
open | query | boolean | No | true: only ongoing incidents. |
Responses:
| Status | Meaning |
|---|---|
| 200 | incidents: id, title, stage (investigating, identified, monitoring, resolved), source (automatic or manual), started_at, resolved_at, issue_id, issue_project, monitors, updates |
| 404 | Monitors are not switched on |
GET /api/maintenance
Maintenance windows (404 unless MONITORS=on); 'running' says whether one is running now
Responses:
| Status | Meaning |
|---|---|
| 200 | windows with starts_at |
POST /api/maintenance
Add a maintenance window. While it runs no incident opens and no alert is sent for the monitors it covers.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 100 characters. |
starts_at | string (date-time) | Yes | |
ends_at | string (date-time) | Yes | |
recurrence | string | No | One of: once, daily, weekly. Default "once". |
all_monitors | boolean | No | |
monitor_ids | array of integer | No | Up to 100 items. |
Responses:
| Status | Meaning |
|---|---|
| 201 | The window |
| 400 | Validation failed |
DELETE /api/maintenance/{id}
Delete a maintenance window
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | From 1 to 2147483647. |
Responses:
| Status | Meaning |
|---|---|
| 204 | Deleted |
| 404 | Not found |
GET /api/me/alert-emails
Your alert email setting in the current organisation (owners also see every member's). 404 unless MONITORS=on.
Responses:
| Status | Meaning |
|---|---|
| 200 | mine {receives, opted_out, included, role}, and members for an owner |
PUT /api/me/alert-emails
Switch your own alert emails on or off. Off always wins. Allowed for every role, a viewer included.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
on | boolean | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | The new setting |
PUT /api/alert-emails/members/{userId}
Owners only. Add a member to the alert emails (included true), remove them (false) or return them to the default (null, owners only).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
userId | path | integer | Yes |
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
included | boolean or null | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | The new settings |
| 403 | Not an owner |
| 404 | Not a member of this organisation |
GET /api/coolify
Admins and owners. Whether Coolify is connected (masked host, last read). The address and token are never returned.
Responses:
| Status | Meaning |
|---|---|
| 200 | The connection status |
| 403 | Not an admin or owner |
PUT /api/coolify
Owners only, as a person. Connect Coolify with a READ-ONLY token (Solo and Team). Stored encrypted; never shown again.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | A public https Coolify address. |
token | string | Yes | An API token with the read permission only (not read:sensitive, write, deploy or root) |
confirmed | boolean | Yes | You are allowed to give AperioFlow this access. Must be true. |
Responses:
| Status | Meaning |
|---|---|
| 200 | Connected |
| 400 | Not confirmed |
| 402 | Not on the Free plan |
| 403 | Not an owner |
| 503 | The server has no DATA_ENCRYPTION_KEYS |
PATCH /api/coolify
Owners only, as a person. Choose (or clear, with null) the project new Coolify monitors go into when none is picked. The project must be one of the organisation's own.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
default_project_id | integer or null | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | The connection status |
| 400 | Not a project of this organisation |
| 403 | Not an owner |
| 404 | Coolify is not connected |
DELETE /api/coolify
Owners only. Delete the stored address and token at once and pause the Coolify monitors.
Responses:
| Status | Meaning |
|---|---|
| 200 | Removed |
POST /api/coolify/discover
Owners only. The names and status of the applications and databases the token can see, with the Coolify project and environment each belongs to (project, environment, null when Coolify does not say) and label ('name | project | environment', the default private monitor name), and which are already monitored. The project and environment names are asked for only here and when monitors are added, never by the minute poll.
Responses:
| Status | Meaning |
|---|---|
| 200 | The resources |
| 409 | Not connected |
| 502 | Coolify refused the token or could not be read |
POST /api/coolify/monitors
Owners only. Monitor the listed resources (only ones Coolify just listed; the plan's monitor limit applies).
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
resources | array of object | Yes | Up to 50 items. |
project_id | integer or null | No | The project the monitors go into. Left out: the connection's default project, if it has one. null: no project. Must be one of the organisation's own. |
Responses:
| Status | Meaning |
|---|---|
| 201 | The monitors created |
| 400 | One is not in the list Coolify gave |
GET /api/webhooks
Owners and admins. The alert webhooks, with the agreement wording. The address is masked and the secret never shown again.
Responses:
| Status | Meaning |
|---|---|
| 200 | The webhooks |
| 403 | Not an owner or admin |
POST /api/webhooks
Owners and admins. Add an alert webhook (at most 5). The secret in the answer is shown once.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
url | string | Yes | A public https address. |
agreed | boolean | Yes | Must be true. |
Responses:
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | Not agreed |
| 403 | Not an owner or admin |
| 409 | Five already |
PATCH /api/webhooks/{id}
Owners and admins. Pause or resume a webhook.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes |
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
active | boolean | No |
Responses:
| Status | Meaning |
|---|---|
| 200 | Updated |
| 404 | Not found |
DELETE /api/webhooks/{id}
Owners and admins. Delete a webhook and its delivery records.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | Deleted |
| 404 | Not found |
POST /api/webhooks/{id}/test
Owners and admins. Send a clearly labelled sample now; nothing is recorded.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | {ok, status_code, reason} |
| 404 | Not found |
GET /heartbeat/{token}
A job's check-in (also POST). No sign-in, the secret token in the address is the credential. 404 for an unknown, paused or switched-off heartbeat. Only the time is stored.
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
token | path | string | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | Recorded |
| 404 | Not found |
| 429 | Too many check-ins |
PATCH /api/monitors/bulk
Members and above. Move up to 100 monitors into one project of the organisation, or out of any with null. All or nothing; one activity line per monitor that changed. The check history and incidents stay with each monitor.
Request body (application/json, required).
| Field | Type | Required | Description |
|---|---|---|---|
ids | array of integer | Yes | Up to 100 items. |
project_id | integer or null | Yes |
Responses:
| Status | Meaning |
|---|---|
| 200 | How many changed: { updated, unchanged, project_id } |
| 400 | Bad ids |
| 403 | A viewer |
| 404 | A monitor is not in this organisation (nothing was changed) |
GET /api/monitors/{id}
One monitor
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | From 1 to 2147483647. |
Responses:
| Status | Meaning |
|---|---|
| 200 | The monitor |
| 404 | Not found |
PATCH /api/monitors/{id}
Change a monitor, or pause it with active false. A new target needs authorised true again. Takes the same settings as adding one, including cert_warn_days (a web monitor only; null sets it back to 30).
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | From 1 to 2147483647. |
Request body (application/json, required)
Responses:
| Status | Meaning |
|---|---|
| 200 | The monitor |
| 400 | Validation failed |
| 404 | Not found |
DELETE /api/monitors/{id}
Delete a monitor
Parameters:
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | From 1 to 2147483647. |
Responses:
| Status | Meaning |
|---|---|
| 204 | Deleted |
| 404 | Not found |