API keys and the public API

Create a key

1. As the workspace owner or an editor, open Workspace settings and find API keys.
2. Name the key, choose read or read and write, and choose when it expires.
3. Copy the key when it is shown. It is not shown again; a lost key is removed and replaced.

A key belongs to the workspace, not to the person who created it, and keeps working when that person leaves. A workspace holds up to 10 keys.

Send requests

Send the key in the Authorization header as Bearer followed by the key, to addresses under /api/v1 on your cheapmonit domain. Requests and answers are JSON. A key works only in its own workspace and can make 120 requests a minute.

A missing, unknown, or expired key answers 401. A read key on a route that changes something answers 403, and so does any key while the workspace is not on Premium.

What the API covers

Read keys: GET /api/v1/monitors and /api/v1/monitors/{id} for monitors with their latest check and a week of uptime, /api/v1/monitors/{id}/checks and /api/v1/monitors/{id}/uptime?days=30 for history, /api/v1/incidents, /api/v1/reports?days=30, and /api/v1/status-pages.

Write keys also POST /api/v1/monitors to add a monitor, PATCH /api/v1/monitors/{id} to change or pause one, DELETE /api/v1/monitors/{id} to remove one, and POST /api/v1/incidents/{id}/acknowledge to acknowledge an outage. A change sends only the settings to set and keeps the rest; enabled false pauses the monitor.

Members, alert channels, on-call schedules, status page editing, account settings, and the keys themselves are managed in the dashboard only.

Keep keys safe

Only a hash of each key is stored. Request header values of monitors are never returned, only their names. The audit log records every change a key makes under the key’s name, and an acknowledgement names the key.

Remove a key in Workspace settings to revoke it at once. Keys stop working if the workspace leaves Premium and can still be removed.