REST API reference

Generated from the API's OpenAPI document (/api/v1/openapi.json). Every path below is relative to https://dash.justmonitorit.com/api/v1. Send your API token as Authorization: Bearer jmi_…; the token role shown for each operation is the lowest role that may call it. Conventions (errors, pagination, idempotency, If-Match, rate limits) are in REST conventions.

Contents

• Token
  • Describe the calling token GET /token
• Organisation
  • Get the organisation GET /orgs/{org}
  • Update the organisation PATCH /orgs/{org}
  • Audit log GET /orgs/{org}/audit-log
  • Plan limits and usage GET /orgs/{org}/entitlements
  • List open invitations GET /orgs/{org}/invites
  • Invite someone POST /orgs/{org}/invites
  • Revoke an invitation DELETE /orgs/{org}/invites/{inv}
  • Resend an invitation POST /orgs/{org}/invites/{inv}/resend
  • List members GET /orgs/{org}/members
  • Change a member's role PATCH /orgs/{org}/members/{usr}
  • Remove a member DELETE /orgs/{org}/members/{usr}
  • Organisation overview GET /orgs/{org}/overview
• Monitors
  • List locations GET /locations
  • List monitors GET /orgs/{org}/monitors
  • Create a monitor POST /orgs/{org}/monitors
  • Run a check once POST /orgs/{org}/monitors/preview-check
  • Get a monitor GET /orgs/{org}/monitors/{mon}
  • Update a monitor PATCH /orgs/{org}/monitors/{mon}
  • Delete a monitor DELETE /orgs/{org}/monitors/{mon}
  • List a monitor's contacts GET /orgs/{org}/monitors/{mon}/contacts
  • Set a monitor's contacts PUT /orgs/{org}/monitors/{mon}/contacts
  • List a monitor's incidents GET /orgs/{org}/monitors/{mon}/incidents
  • Pause a monitor POST /orgs/{org}/monitors/{mon}/pause
  • List heartbeat pings GET /orgs/{org}/monitors/{mon}/pings
  • List check results GET /orgs/{org}/monitors/{mon}/results
  • Resume a monitor POST /orgs/{org}/monitors/{mon}/resume
  • List rollups GET /orgs/{org}/monitors/{mon}/rollups
  • Response-time series GET /orgs/{org}/monitors/{mon}/series
  • Status timeline GET /orgs/{org}/monitors/{mon}/timeline
  • List path traces GET /orgs/{org}/monitors/{mon}/traces
  • Run a path trace POST /orgs/{org}/monitors/{mon}/traces
  • Uptime GET /orgs/{org}/monitors/{mon}/uptime
  • Get a path trace GET /orgs/{org}/traces/{trc}
• Incidents
  • List incidents GET /orgs/{org}/incidents
  • Get an incident GET /orgs/{org}/incidents/{inc}
  • Acknowledge an incident POST /orgs/{org}/incidents/{inc}/acknowledge
  • Add a note to an incident POST /orgs/{org}/incidents/{inc}/notes
• Contacts
  • List contacts GET /orgs/{org}/contacts
  • Create a contact POST /orgs/{org}/contacts
  • Get a contact GET /orgs/{org}/contacts/{con}
  • Update a contact PATCH /orgs/{org}/contacts/{con}
  • Delete a contact DELETE /orgs/{org}/contacts/{con}
  • Disable a contact POST /orgs/{org}/contacts/{con}/disable
  • Enable a contact POST /orgs/{org}/contacts/{con}/enable
  • Set a contact's monitors PUT /orgs/{org}/contacts/{con}/monitors
  • Send a test notification POST /orgs/{org}/contacts/{con}/test
  • Verify a contact POST /orgs/{org}/contacts/{con}/verify
  • Send a verification code POST /orgs/{org}/contacts/{con}/verify/send
• Notifications
  • List notifications GET /orgs/{org}/notifications
  • Get a notification GET /orgs/{org}/notifications/{ntf}
• Maintenance windows
  • List maintenance windows GET /orgs/{org}/maintenance
  • Schedule a maintenance window POST /orgs/{org}/maintenance
  • Get a maintenance window GET /orgs/{org}/maintenance/{mnt}
  • Change a maintenance window PATCH /orgs/{org}/maintenance/{mnt}
  • Delete a maintenance window DELETE /orgs/{org}/maintenance/{mnt}
  • End a maintenance window now POST /orgs/{org}/maintenance/{mnt}/end
• Billing
  • List plans GET /billing/plans
  • Billing state GET /orgs/{org}/billing
• Schemas

Token

Describe the calling token

GET /token · token role: viewer

The token making the request, the organisation it belongs to and its effective role (the lower of the token's role and its creator's current role). Use it to find the org id for the other paths. Only API tokens can call it.

Responses

• 200: TokenInfo
• Errors: 401 unauthenticated (no, or an invalid, API token); 403 account_suspended; 429 rate_limited

Organisation

Get the organisation

GET /orgs/{org} · token role: viewer

Name, timezone, state, your effective role (my_role) and plan of the organisation.

Path parameters

Responses

• 200: Org
• Errors: 401 unauthenticated; 403 account_suspended; 404 not_found; 429 rate_limited

Update the organisation

PATCH /orgs/{org} · token role: admin

Rename the organisation or change its timezone (an IANA name such as Europe/London).

Path parameters

Request body (OrgPatch)

Responses

• 200: Org
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, billing_inactive; 404 not_found; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Audit log

GET /orgs/{org}/audit-log · token role: admin

Who did what in the organisation, newest first. Entries made with an API token carry data.api_token ({id, name}).

Path parameters

Query parameters

Responses

• 200: page of AuditEntry
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 422 validation (/query/...); 429 rate_limited

Plan limits and usage

GET /orgs/{org}/entitlements · token role: viewer

What the organisation may do right now (monitor count, minimum interval, locations per monitor, checks per minute, contacts, seats, SMS credits, retention) and how much of it is used.

Path parameters

Responses

• 200: OrgEntitlements
• Errors: 401 unauthenticated; 403 account_suspended, org_deleting; 404 not_found (unknown org or not a member); 429 rate_limited

List open invitations

GET /orgs/{org}/invites · token role: admin

Invitations that have not been accepted, revoked or expired, newest first.

Path parameters

Query parameters

Responses

• 200: page of Invite
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 422 validation (/query/cursor, /query/limit); 429 rate_limited

Invite someone

POST /orgs/{org}/invites · token role: admin

Email an invitation to join the organisation with a role (admin, member or viewer; owner invitations need a signed-in owner). The invitation is valid for 7 days. Counts against the plan's seats.

Path parameters

Headers

Request body (CreateInviteRequest)

Responses

• 201: Invite
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, plan_limit (seats), org_suspended, org_deleting, billing_inactive; 404 not_found; 409 conflict (already a member or invited), idempotency_in_progress; 413 payload_too_large; 415 unsupported_media_type; 422 validation, idempotency_mismatch; 429 rate_limited (20 per day)

Revoke an invitation

DELETE /orgs/{org}/invites/{inv} · token role: admin

The link in the invitation email stops working.

Path parameters

Responses

• 204: no body (revoked)
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, billing_inactive; 404 not_found; 429 rate_limited

Resend an invitation

POST /orgs/{org}/invites/{inv}/resend · token role: admin

Send the invitation again with a new link (the old link stops working) and a fresh 7-day expiry.

Path parameters

Responses

• 202: no body (sent)
• Errors: 401 unauthenticated; 403 forbidden, plan_limit, org_suspended, org_deleting, billing_inactive; 404 not_found; 429 rate_limited

List members

GET /orgs/{org}/members · token role: viewer

Every member of the organisation with their role and when they were last active.

Path parameters

Responses

• 200: list of Member
• Errors: 401 unauthenticated; 403 org_suspended, org_deleting; 404 not_found; 429 rate_limited

Change a member's role

PATCH /orgs/{org}/members/{usr} · token role: admin

Set a member's role to admin, member or viewer. Granting or removing owner is not possible with a token. If the member is demoted below the role of one of their API tokens, that token is revoked.

Path parameters

Request body (RoleRequest)

Responses

• 200: Member
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, billing_inactive; 404 not_found; 409 sole_owner; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Remove a member

DELETE /orgs/{org}/members/{usr} · token role: admin

Remove a member from the organisation; their API tokens for it are deleted. Removing an owner, or the token's own creator (leaving), is not possible with a token.

Path parameters

Responses

• 204: no body (removed)
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 409 sole_owner; 429 rate_limited

Organisation overview

GET /orgs/{org}/overview · token role: viewer

Monitor counts by status, open incidents (newest first, at most 20), the latest status changes and usage against the plan.

Path parameters

Responses

• 200: Overview
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Monitors

List locations

GET /locations · token role: none (public)

The active check locations and the regions they belong to. Monitors name locations by code (lon1) or by region. No authentication needed.

Responses

• 200: LocationsResponse
• Errors: 429 rate_limited

List monitors

GET /orgs/{org}/monitors · token role: viewer

The organisation's monitors, filtered and sorted, with cursor pagination (up to 500 per page).

Path parameters

Query parameters

Responses

• 200: page of Monitor
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Create a monitor

POST /orgs/{org}/monitors · token role: member

Validate and create a monitor. It starts checking at once unless paused is true. Send an Idempotency-Key so a retried request does not create a second monitor. 403 plan_limit names the limit that would be exceeded.

Path parameters

Headers

Request body (MonitorInput)

Responses

• 201: Monitor, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, plan_limit, org_suspended, org_deleting, account_suspended; 404 not_found; 409 idempotency_in_progress; 413 payload_too_large; 415 unsupported_media_type; 422 validation, idempotency_mismatch; 429 rate_limited

Run a check once

POST /orgs/{org}/monitors/preview-check · token role: member

Run a check from one location now and return the result, without creating a monitor or storing anything. The same validation as creating a monitor applies. Waits for the probe (up to the check's time budget plus 15 seconds); 503 unavailable if no probe in that location can run it.

Path parameters

Request body (PreviewCheckInput)

Responses

• 200: CheckResult
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited; 503 unavailable

Get a monitor

GET /orgs/{org}/monitors/{mon} · token role: viewer

One monitor with its current state per location and its uptime over the last 24 hours. The ETag header carries version for If-Match.

Path parameters

Responses

• 200: Monitor, header ETag
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Update a monitor

PATCH /orgs/{org}/monitors/{mon} · token role: member

Change any field except kind (JSON merge patch: omitted fields are unchanged, null clears a nullable field, arrays are replaced whole; spec is merged field by field). Send If-Match: "<version>" to get 412 precondition_failed instead of overwriting someone else's change.

Path parameters

Headers

Request body (MonitorPatch)

Responses

• 200: Monitor, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, plan_limit, org_suspended, org_deleting, account_suspended; 404 not_found; 412 precondition_failed; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Delete a monitor

DELETE /orgs/{org}/monitors/{mon} · token role: member

Delete a monitor with its results, incidents and pending notifications. No notification is sent.

Path parameters

Headers

Responses

• 204: no body (deleted)
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 412 precondition_failed; 422 validation; 429 rate_limited

List a monitor's contacts

GET /orgs/{org}/monitors/{mon}/contacts · token role: viewer

The contacts notified for a monitor.

Path parameters

Responses

• 200: list of Contact
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Set a monitor's contacts

PUT /orgs/{org}/monitors/{mon}/contacts · token role: member

Replace the set of contacts notified for a monitor.

Path parameters

Headers

Request body (MonitorContactIds)

Responses

• 200: MonitorContactIds
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 412 precondition_failed; 415 unsupported_media_type; 422 validation; 429 rate_limited

List a monitor's incidents

GET /orgs/{org}/monitors/{mon}/incidents · token role: viewer

Incidents of one monitor, newest first, within the plan's history.

Path parameters

Query parameters

Responses

• 200: page of Incident
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Pause a monitor

POST /orgs/{org}/monitors/{mon}/pause · token role: member

Stop checking until resumed. Pausing resolves an open incident. Idempotent.

Path parameters

Responses

• 200: Monitor, header ETag
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 429 rate_limited

List heartbeat pings

GET /orgs/{org}/monitors/{mon}/pings · token role: viewer

A heartbeat monitor's ping history, newest first: when each ping arrived, success or fail (the job requested the ping URL followed by /fail), the method, the client's address and user agent. The newest 100 are kept; other kinds have none.

Path parameters

Query parameters

Responses

• 200: list of HeartbeatPing
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

List check results

GET /orgs/{org}/monitors/{mon}/results · token role: viewer

Raw results of a monitor, newest first. The window defaults to the last 24 hours, spans at most 7 days, and starts no earlier than the plan's raw data retention.

Path parameters

Query parameters

Responses

• 200: page of CheckResult
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Resume a monitor

POST /orgs/{org}/monitors/{mon}/resume · token role: member

Start checking again. 403 plan_limit if the plan no longer allows the monitor.

Path parameters

Responses

• 200: Monitor, header ETag
• Errors: 401 unauthenticated; 403 forbidden, plan_limit, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 422 validation; 429 rate_limited

List rollups

GET /orgs/{org}/monitors/{mon}/rollups · token role: viewer

Hourly (hour, at most 31 days) or daily (day, at most 731 days) aggregates per location: check counts by outcome and latency statistics. Not paginated.

Path parameters

Query parameters

Responses

• 200: RollupsResponse
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Response-time series

GET /orgs/{org}/monitors/{mon}/series · token role: viewer

Median response time per location over 24h, 7d, 30d or 90d, with the periods the monitor was not up.

Path parameters

Query parameters

Responses

• 200: Series
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Status timeline

GET /orgs/{org}/monitors/{mon}/timeline · token role: viewer

The status periods (up, down, degraded, no data, paused) overlapping a window, oldest first.

Path parameters

Query parameters

Responses

• 200: list of StatusPeriod
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

List path traces

GET /orgs/{org}/monitors/{mon}/traces · token role: viewer

Traceroute/MTR runs towards a monitor's target, newest first, within the plan's raw data retention. Traces run automatically when an incident opens.

Path parameters

Query parameters

Responses

• 200: list of PathTrace
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Run a path trace

POST /orgs/{org}/monitors/{mon}/traces · token role: member

Trace the network path to the monitor's target from a location (mtr by default, about 15 seconds; traceroute about 5). Returns at once with status: pending; poll GET /orgs/{org}/traces/{trc} for the result.

Path parameters

Request body (PathTraceInput)

Responses

• 202: PathTrace
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 conflict (a trace from this location is still running); 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited; 503 unavailable (no probe there can run it)

Uptime

GET /orgs/{org}/monitors/{mon}/uptime · token role: viewer

Uptime ratio and seconds down, degraded, without data and paused, for named windows (24h, 7d, 30d, 90d) or a from/to range. Degraded counts as up; paused and no-data time is left out of the ratio.

Path parameters

Query parameters

Responses

• 200: list of Uptime
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Get a path trace

GET /orgs/{org}/traces/{trc} · token role: viewer

One path trace with its hops.

Path parameters

Responses

• 200: PathTrace
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Incidents

List incidents

GET /orgs/{org}/incidents · token role: viewer

The organisation's incidents, newest first, filtered by status, monitor, severity and time.

Path parameters

Query parameters

Responses

• 200: page of Incident
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 422 validation; 429 rate_limited

Get an incident

GET /orgs/{org}/incidents/{inc} · token role: viewer

One incident with its timeline events and the notifications it sent.

Path parameters

Responses

• 200: IncidentDetail
• Errors: 401 unauthenticated; 403 forbidden, account_suspended, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Acknowledge an incident

POST /orgs/{org}/incidents/{inc}/acknowledge · token role: member

Mark an open incident as acknowledged: reminders stop. Idempotent; 409 incident_resolved once it is resolved.

Path parameters

Responses

• 200: Incident
• Errors: 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 incident_resolved; 429 rate_limited; 503 unavailable

Add a note to an incident

POST /orgs/{org}/incidents/{inc}/notes · token role: member

Add a note (1-2000 characters) to an incident's timeline.

Path parameters

Request body (IncidentNoteInput)

Responses

• 201: IncidentEvent
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Contacts

List contacts

GET /orgs/{org}/contacts · token role: viewer

The organisation's contacts (email, SMS, phone calls, Pushover, Discord, PagerDuty, Slack, webhooks), oldest first. Secrets are never returned.

Path parameters

Query parameters

Responses

• 200: page of Contact
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 422 validation; 429 rate_limited

Create a contact

POST /orgs/{org}/contacts · token role: member

Create a contact. Email, SMS and voice contacts start unverified and are sent a 6-digit code (an SMS code uses one SMS credit; a voice contact gets a call that reads the code, which uses a call's credits); Pushover and Discord contacts are validated with the provider and start active; PagerDuty contacts (an Events API v2 integration key) are checked offline and start active; Slack contacts (an incoming webhook URL) are checked with Slack and start active; webhook contacts start active when their host has the organisation's TXT record (config.txt_name, config.txt_value), else unverified until a re-check finds it; Microsoft Teams contacts (a Workflows webhook URL) start unverified and get a 6-digit code posted into the channel.

Path parameters

Headers

Request body (ContactInput)

Responses

• 201: Contact, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, plan_limit, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 sms_allowance_exhausted, idempotency_in_progress; 413 payload_too_large; 415 unsupported_media_type; 422 validation, idempotency_mismatch; 429 rate_limited; 503 unavailable

Get a contact

GET /orgs/{org}/contacts/{con} · token role: viewer

One contact. The ETag header carries version for If-Match.

Path parameters

Responses

• 200: Contact, header ETag
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 429 rate_limited

Update a contact

PATCH /orgs/{org}/contacts/{con} · token role: member

Change any field except kind (JSON merge patch). Changing an email address, phone number or Teams webhook URL makes the contact unverified again and sends a new code. A secret that is omitted is kept.

Path parameters

Headers

Request body (ContactPatch)

Responses

• 200: Contact, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 conflict, sms_allowance_exhausted; 412 precondition_failed; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited; 503 unavailable

Delete a contact

DELETE /orgs/{org}/contacts/{con} · token role: member

Delete a contact; it is removed from every monitor and its pending notifications are dropped.

Path parameters

Headers

Responses

• 204: no body (deleted)
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 412 precondition_failed; 422 validation; 429 rate_limited

Disable a contact

POST /orgs/{org}/contacts/{con}/disable · token role: member

Stop sending to a contact (disabled_reason = "user") without deleting it.

Path parameters

Responses

• 200: Contact, header ETag
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting, account_suspended; 404 not_found; 429 rate_limited

Enable a contact

POST /orgs/{org}/contacts/{con}/enable · token role: member

Re-enable a contact disabled by a user or after repeated delivery failures. Other disabled states (bounce, complaint, unsubscribe, invalid) return through verification or a signed-in owner or admin.

Path parameters

Responses

• 200: Contact, header ETag
• Errors: 401 unauthenticated; 403 forbidden (also: a bounced address and the caller is not an owner or admin), billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 conflict (also: the address bounced before it was verified, or the email provider lists it for a complaint); 429 rate_limited (also: a bounced address was reactivated less than 24 h ago); 503 unavailable (the email provider could not reactivate the address)

Set a contact's monitors

PUT /orgs/{org}/contacts/{con}/monitors · token role: member

Replace the set of monitors a contact is notified for.

Path parameters

Headers

Request body (ContactMonitors)

Responses

• 200: ContactMonitors, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 412 precondition_failed; 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Send a test notification

POST /orgs/{org}/contacts/{con}/test · token role: member

Queue a test message to an active contact and return the notification id; follow it with GET /orgs/{org}/notifications/{ntf}. 409 contact_unverified, contact_disabled or sms_allowance_exhausted when it cannot be sent.

Path parameters

Headers

Responses

• 202: TestSent
• Errors: 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 contact_unverified, contact_disabled, sms_allowance_exhausted, idempotency_in_progress, conflict; 422 validation, idempotency_mismatch; 429 rate_limited

Verify a contact

POST /orgs/{org}/contacts/{con}/verify · token role: member

Verify an email, SMS, voice or Teams contact with the 6-digit code it received. A wrong code is 422 validation with errors[0].code = "invalid_code"; after 5 wrong codes the code is void.

Path parameters

Request body (VerifyInput)

Responses

• 200: Contact, header ETag
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 conflict; 413 payload_too_large; 415 unsupported_media_type; 422 validation (invalid_code, with attempts_left); 429 rate_limited

Send a verification code

POST /orgs/{org}/contacts/{con}/verify/send · token role: member

Send a new code to an email, SMS, voice or Teams contact, or validate a Pushover, Discord, PagerDuty or Slack contact again, or look for a webhook's TXT record again (it becomes active on success).

Path parameters

Responses

• 202: no body (code sent, or validation passed)
• Errors: 401 unauthenticated; 403 forbidden, billing_inactive, org_suspended, org_deleting, account_suspended; 404 not_found; 409 conflict, sms_allowance_exhausted; 422 validation (pushover_invalid, discord_webhook_invalid); 429 rate_limited; 503 unavailable

Notifications

List notifications

GET /orgs/{org}/notifications · token role: viewer

The organisation's notification log, newest first, with each delivery attempt. Filter by contact, incident, monitor, status or kind.

Path parameters

Query parameters

Responses

• 200: page of Notification
• Errors: 400 bad_request; 401 unauthenticated; 403 org_suspended, org_deleting, account_suspended; 404 not_found (not a member); 422 validation (bad filter or cursor); 429 rate_limited

Get a notification

GET /orgs/{org}/notifications/{ntf} · token role: viewer

One notification with its delivery attempts and provider status.

Path parameters

Responses

• 200: Notification
• Errors: 401 unauthenticated; 403 org_suspended, org_deleting, account_suspended; 404 not_found; 429 rate_limited

Maintenance windows

List maintenance windows

GET /orgs/{org}/maintenance · token role: viewer

Active and upcoming maintenance windows, and those that ended in the last 30 days, by start. While a window is active, the monitors it covers keep checking and record incidents, but their alerts are held until it ends.

Path parameters

Responses

• 200: list of MaintenanceWindow
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Schedule a maintenance window

POST /orgs/{org}/maintenance · token role: member

Hold the alerts of all monitors (all_monitors: true, including monitors added later) or of monitor_ids from starts_at (default now) until ends_at, or for duration_minutes; at most 7 days. When it ends, each incident still open alerts its contacts once; incidents that ended inside the window send nothing.

Path parameters

Request body (CreateMaintenanceRequest)

Responses

• 201: MaintenanceWindow
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 409 conflict (50 windows that have not ended); 413 payload_too_large; 415 unsupported_media_type; 422 validation; 429 rate_limited

Get a maintenance window

GET /orgs/{org}/maintenance/{mnt} · token role: viewer

One maintenance window, with state (upcoming, active or ended) and the number of incidents whose alerts it holds now.

Path parameters

Responses

• 200: MaintenanceWindow
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 429 rate_limited

Change a maintenance window

PATCH /orgs/{org}/maintenance/{mnt} · token role: member

Rename a window that has not ended or move its end (for example to extend it); the start can only move before the window starts.

Path parameters

Request body (UpdateMaintenanceRequest)

Responses

• 200: MaintenanceWindow
• Errors: 400 bad_request; 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 409 conflict (the window has ended); 415 unsupported_media_type; 422 validation; 429 rate_limited

Delete a maintenance window

DELETE /orgs/{org}/maintenance/{mnt} · token role: member

Delete a window that has not started. To stop an active window, end it instead.

Path parameters

Responses

• 204: no body (deleted)
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 409 conflict (started: end it instead); 429 rate_limited

End a maintenance window now

POST /orgs/{org}/maintenance/{mnt}/end · token role: member

End an active window now. Within seconds, each incident still open alerts its contacts once.

Path parameters

Responses

• 200: MaintenanceWindow
• Errors: 401 unauthenticated; 403 forbidden, org_suspended, org_deleting; 404 not_found; 409 conflict (not started: delete it; or already ended); 429 rate_limited

Billing

List plans

GET /billing/plans · token role: none (public)

The plans on sale with their prices and limits. No authentication needed.

Responses

• 200: list of PlanOffer
• Errors: 404 billing_disabled ([billing] mode = "disabled"); 429 rate_limited; 503 unavailable: Stripe not configured, unreachable, or a catalogue price is missing

Billing state

GET /orgs/{org}/billing · token role: viewer

The organisation's plan, subscription state, entitlements and usage. Checkout and the customer portal need a signed-in owner.

Path parameters

Responses

• 200: Billing
• Errors: 401 unauthenticated; 403 account_suspended, org_deleting; 404 not_found (unknown org or not a member), billing_disabled ([billing] mode = "disabled"; use GET /orgs/{org}/entitlements); 429 rate_limited

Schemas

Response and request objects referenced above. Every field of a response is present; absent values are null.

ApiToken

An API token (never its secret).

Assertion

An http_adv assertion.

With type = body_contains:

With type = body_not_contains:

With type = body_regex:

With type = json_path:

With type = header:

Billing

An org's subscription, entitlements and usage.

BillingUsage

Current usage of an org (Billing.usage).

CheckResult

One check result.

CheckTimings

Phase timings of a result.

Contact

A contact (secrets are never returned; secret_set says whether one is stored).

ContactInput

POST /orgs/{org}/contacts body.

ContactMonitors

PUT .../monitors body and response.

ContactPatch

PATCH /orgs/{org}/contacts/{con} body (JSON merge patch; kind is immutable, config is merged, secret replaces the stored one).

ContactRef

{ "id": "con_…", "name": "…", "kind": "sms" }.

CreateInviteRequest

{email, role}.

CreateMaintenanceRequest

POST /orgs/{org}/maintenance body. Give ends_at or duration_minutes, and all_monitors: true or monitor_ids.

DeliveryView

One delivery attempt of a notification.

DomainExpirySpec

domain_expiry.

Entitlements

The single answer to "what may this org do now".

HeaderSpec

One request header of an http_adv check.

HeartbeatSpec

heartbeat. The period between pings is the monitor's interval_s.

HttpAdvSpec

http_adv spec in responses. A secret header has "secret": true, "value": null.

HttpAdvSpecInput

http_adv spec in requests. A header with secret: true carries its write-only value in value.

HttpAuthInput

auth of an http_adv spec in requests. A secret that is absent or null keeps the stored value; "" clears it.

With type = none:

With type = basic:

With type = bearer:

HttpAuthView

auth of an http_adv spec in responses: whether each secret is stored, never its value.

With type = none:

With type = basic:

With type = bearer:

HttpSpec

http.

IcmpSpec

icmp.

Incident

An incident.

IncidentDetail

An incident with its timeline and notifications.

Every field of Incident, and:

IncidentEvent

One timeline entry of an incident.

IncidentMonitor

{ "id": "mon_…", "name": "…" }.

IncidentNoteInput

POST .../notes body.

Invite

An open invitation.

Location

A customer-selectable location.

LocationsResponse

GET /locations response.

MailSpec

imap and smtp.

MaintenanceWindow

A maintenance window: while it is active, the monitors it covers keep checking and record incidents, but their alerts are held. When it ends, each incident still open alerts its contacts once; incidents that ended inside the window send nothing.

Member

One member of an org.

MemberUser

The user part of a member.

Monitor

A monitor. Secret values are never returned.

MonitorContactIds

PUT .../contacts body and response.

MonitorInput

POST /orgs/{org}/monitors body.

MonitorLocationState

One location of a monitor's live state.

MonitorLocations

The location selection of a monitor.

MonitorLocationsInput

Location selection of a monitor (MonitorInput.locations).

MonitorPatch

PATCH /orgs/{org}/monitors/{mon} body: any subset of MonitorInput except kind (JSON merge patch; spec is merged per RFC 7396).

MonitorSpec

A monitor's spec in responses: the schema of its kind, with every field present (defaults applied, hosts and URLs normalised). Secrets of http_adv show as flags (HttpAdvSpec).

The schema of the monitor's kind:

MonitorSpecInput

A monitor's spec in requests: the schema of its kind (imap and smtp share MailSpec), without a type tag. Secret values of http_adv are sent inline (HttpAdvSpecInput).

The schema of the monitor's kind:

MonitorState

A monitor's live state.

Notification

One notification_jobs row.

Org

An organisation as its member sees it.

OrgBilling

{plan, status}; status is effective (a lapsed trial or grace period counts as canceled).

OrgEntitlements

The org's effective entitlements and current usage (GET /orgs/{org}/entitlements): what forms and limit messages need, in either billing mode.

OrgPatch

PATCH /orgs/{org} (merge patch).

Overview

The org dashboard.

OverviewChange

One status change.

OverviewMonitors

Monitors per status; paused counts every monitor not running.

OverviewUsage

Plan usage.

PathTrace

A path trace.

PathTraceInput

POST .../traces body.

PreviewCheckInput

POST .../preview-check body.

RegionView

A region with at least one active location.

RoleRequest

{role}.

Rollup

One rollup bucket.