API reference

Every endpoint, parameter, and schema. Generated from the API's OpenAPI document, so it always matches the deployed backend.

63 endpoints across 11 groups, from UptimeX API v1.1.0. Authenticate with a project API key as described in the REST API guide.

https://api.uptimex.co

Monitors

get/v1/monitors

List monitors

Every monitor the credential can see (an API key: its project's), oldest first, with current status, 24h aggregates and the last 30 check results. Not paginated.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/monitors

Create a monitor

Creates the monitor and, for every type but heartbeat and scheduler, runs its first check in the background. `status` is null until that completes. An API key creates in its own project.

Request body · MonitorInput

Field	Type	Description
`type`	string	What the monitor checks. `http` polls a URL; `keyword` is http plus at least one content rule; `api` is http with JSON-field rules (paid); `heartbeat` waits for your job to ping it; `scheduler` calls your URL on a schedule and treats 2xx as success (paid); `port` opens a TCP connection to host:port; `dns` resolves a record (paid). Cannot be changed after creation.`httpkeywordapiheartbeatschedulerdnsport`Default: `"http"`
`name`	string	Default: `"Untitled"`
`url`	string	http / keyword / api / scheduler: the URL to call. Required for those types. Public hosts only (`invalid_target` otherwise).
`method`	string	http / keyword / api: HEAD is switched to GET when content rules are set. scheduler: one of GET, POST, PUT, PATCH, DELETE (a trigger must act), default POST.`HEADGETPOSTPUTPATCHDELETEOPTIONS`Default: `"HEAD"`
`interval_sec`	integer	Seconds between checks, raised to the project owner's plan minimum (free 300s, pro 60s, team 60s). heartbeat: the longest allowed gap between pings.
`grace_sec`	integer	heartbeat only: extra seconds after `interval_sec` before the monitor goes down.Default: `60`
`slow_ms`	integer	http / keyword / api: latency at or above this is `slow`.Default: `1500`
`timeout_ms`	integer	Request timeout, clamped to 1000 to 60000. Not used by heartbeat.Default: `10000`
`expect_status`	integer \| null	http / keyword / api: exact status code required. null or 0 accepts any 2xx or 3xx.
`follow_redirects`	boolean	http / keyword / api: follow 3xx and judge the final response. Off by default (a 3xx counts as reachable).
`check_ssl`	boolean	https only, paid (`plan_required` with `feature: advanced_monitoring` otherwise): report a certificate or TLS failure as a distinct SSL problem and track the certificate expiry.
`check_domain`	boolean	Paid (`feature: advanced_monitoring`): look up the domain's registration expiry over RDAP and warn before it lapses.
`content_rules`	ContentRule[]	http / keyword / api: up to 4 rules the response must satisfy. keyword needs at least one (`keyword_needs_rule`). json_field rules are paid (`feature: advanced_monitoring`).
`request_headers`	HeaderInput[]	http / keyword / api / scheduler: up to 4 headers sent with every check. Values are encrypted and never returned.
`request_body`	string	http / keyword / api / scheduler: body for POST, PUT, PATCH or DELETE (`invalid_body` with GET or HEAD, or over 8 KB). Sent with every check, so point writes at test data. `application/json` unless a Content-Type header is set.
`host`	string	port / dns: bare hostname, no scheme, path or port. Required for those types. port accepts a public IP literal; dns does not.
`port`	integer	port only: TCP port to connect to. Required.
`dns_record_type`	string	dns only: record type to resolve.`AAAAACNAMEMXTXTNS`Default: `"A"`
`dns_expected_value`	string	dns only: a string one of the answers must contain. Omit to accept any answer.
`fail_threshold`	integer	Consecutive failed checks before `down`. Not used by heartbeat or scheduler.Default: `3`
`recover_threshold`	integer	Consecutive good checks before `up` again.Default: `1`
`project_id`	string	Project to create the monitor in. An API key always creates in its own project, whatever is sent here.

Responses

201CreatedMonitor
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`monitor_limit`: the owner's plan cap is reached (`limit`; free 5, pro 30, team 50). `plan_required`: `feature: monitor_type` for api, scheduler or dns on a free plan; `feature: advanced_monitoring` for check_ssl, check_domain or a json_field rule on a free plan.Error
404`not_found`: `project_id` is not a project the caller can create in.Error
422`invalid_target`, `invalid_headers`, `invalid_body`, `invalid_content_rules`, `keyword_needs_rule`, `invalid_method`; `invalid` (`field`) for a value of the wrong type.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/monitors/test

Run one check without saving

Takes the same body as an http, keyword or api create and runs a single check. Nothing is stored. Every header must carry a value (nothing stored to keep).

Request body · MonitorInput

Field	Type	Description
`type`	string	What the monitor checks. `http` polls a URL; `keyword` is http plus at least one content rule; `api` is http with JSON-field rules (paid); `heartbeat` waits for your job to ping it; `scheduler` calls your URL on a schedule and treats 2xx as success (paid); `port` opens a TCP connection to host:port; `dns` resolves a record (paid). Cannot be changed after creation.`httpkeywordapiheartbeatschedulerdnsport`Default: `"http"`
`name`	string	Default: `"Untitled"`
`url`	string	http / keyword / api / scheduler: the URL to call. Required for those types. Public hosts only (`invalid_target` otherwise).
`method`	string	http / keyword / api: HEAD is switched to GET when content rules are set. scheduler: one of GET, POST, PUT, PATCH, DELETE (a trigger must act), default POST.`HEADGETPOSTPUTPATCHDELETEOPTIONS`Default: `"HEAD"`
`interval_sec`	integer	Seconds between checks, raised to the project owner's plan minimum (free 300s, pro 60s, team 60s). heartbeat: the longest allowed gap between pings.
`grace_sec`	integer	heartbeat only: extra seconds after `interval_sec` before the monitor goes down.Default: `60`
`slow_ms`	integer	http / keyword / api: latency at or above this is `slow`.Default: `1500`
`timeout_ms`	integer	Request timeout, clamped to 1000 to 60000. Not used by heartbeat.Default: `10000`
`expect_status`	integer \| null	http / keyword / api: exact status code required. null or 0 accepts any 2xx or 3xx.
`follow_redirects`	boolean	http / keyword / api: follow 3xx and judge the final response. Off by default (a 3xx counts as reachable).
`check_ssl`	boolean	https only, paid (`plan_required` with `feature: advanced_monitoring` otherwise): report a certificate or TLS failure as a distinct SSL problem and track the certificate expiry.
`check_domain`	boolean	Paid (`feature: advanced_monitoring`): look up the domain's registration expiry over RDAP and warn before it lapses.
`content_rules`	ContentRule[]	http / keyword / api: up to 4 rules the response must satisfy. keyword needs at least one (`keyword_needs_rule`). json_field rules are paid (`feature: advanced_monitoring`).
`request_headers`	HeaderInput[]	http / keyword / api / scheduler: up to 4 headers sent with every check. Values are encrypted and never returned.
`request_body`	string	http / keyword / api / scheduler: body for POST, PUT, PATCH or DELETE (`invalid_body` with GET or HEAD, or over 8 KB). Sent with every check, so point writes at test data. `application/json` unless a Content-Type header is set.
`host`	string	port / dns: bare hostname, no scheme, path or port. Required for those types. port accepts a public IP literal; dns does not.
`port`	integer	port only: TCP port to connect to. Required.
`dns_record_type`	string	dns only: record type to resolve.`AAAAACNAMEMXTXTNS`Default: `"A"`
`dns_expected_value`	string	dns only: a string one of the answers must contain. Omit to accept any answer.
`fail_threshold`	integer	Consecutive failed checks before `down`. Not used by heartbeat or scheduler.Default: `3`
`recover_threshold`	integer	Consecutive good checks before `up` again.Default: `1`
`project_id`	string	Project to create the monitor in. An API key always creates in its own project, whatever is sent here.

Responses

200Check result, with a response body snippetCheckResult
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
422`invalid_target`, `invalid_headers`, `invalid_body`, `invalid_content_rules`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/monitors/{id}

Get a monitor

The full editable configuration plus current status. Header values are never returned.

Parameters

idpath · requiredMonitor id.

Responses

200OKMonitor
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/monitors/{id}

Update a monitor

Partial update; returns the updated monitor. Send `{"enabled": false}` to pause and `true` to resume.

Parameters

idpath · requiredMonitor id.

Request body · MonitorPatch

Field	Type	Description
`name`	string	Default: `"Untitled"`
`url`	string	http / keyword / api / scheduler: the URL to call. Required for those types. Public hosts only (`invalid_target` otherwise).
`method`	string	http / keyword / api: HEAD is switched to GET when content rules are set. scheduler: one of GET, POST, PUT, PATCH, DELETE (a trigger must act), default POST.`HEADGETPOSTPUTPATCHDELETEOPTIONS`Default: `"HEAD"`
`interval_sec`	integer	Seconds between checks, raised to the project owner's plan minimum (free 300s, pro 60s, team 60s). heartbeat: the longest allowed gap between pings.
`grace_sec`	integer	heartbeat only: extra seconds after `interval_sec` before the monitor goes down.Default: `60`
`slow_ms`	integer	http / keyword / api: latency at or above this is `slow`.Default: `1500`
`timeout_ms`	integer	Request timeout, clamped to 1000 to 60000. Not used by heartbeat.Default: `10000`
`expect_status`	integer \| null	http / keyword / api: exact status code required. null or 0 accepts any 2xx or 3xx.
`follow_redirects`	boolean	http / keyword / api: follow 3xx and judge the final response. Off by default (a 3xx counts as reachable).
`check_ssl`	boolean	https only, paid (`plan_required` with `feature: advanced_monitoring` otherwise): report a certificate or TLS failure as a distinct SSL problem and track the certificate expiry.
`check_domain`	boolean	Paid (`feature: advanced_monitoring`): look up the domain's registration expiry over RDAP and warn before it lapses.
`content_rules`	ContentRule[]	http / keyword / api: up to 4 rules the response must satisfy. keyword needs at least one (`keyword_needs_rule`). json_field rules are paid (`feature: advanced_monitoring`).
`request_headers`	HeaderInput[]	http / keyword / api / scheduler: up to 4 headers sent with every check. Values are encrypted and never returned.
`request_body`	string	http / keyword / api / scheduler: body for POST, PUT, PATCH or DELETE (`invalid_body` with GET or HEAD, or over 8 KB). Sent with every check, so point writes at test data. `application/json` unless a Content-Type header is set.
`host`	string	port / dns: bare hostname, no scheme, path or port. Required for those types. port accepts a public IP literal; dns does not.
`port`	integer	port only: TCP port to connect to. Required.
`dns_record_type`	string	dns only: record type to resolve.`AAAAACNAMEMXTXTNS`Default: `"A"`
`dns_expected_value`	string \| null	dns only. null clears the answer check.
`fail_threshold`	integer	Consecutive failed checks before `down`. Not used by heartbeat or scheduler.Default: `3`
`recover_threshold`	integer	Consecutive good checks before `up` again.Default: `1`
`enabled`	boolean	false pauses the monitor, true resumes it.
`project_id`	string \| null	Move the monitor to another project; null makes it ungrouped. An API key cannot move a monitor out of its project.

Responses

200UpdatedMonitor
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: advanced_monitoring`): check_ssl, check_domain or a json_field rule on a free-plan project.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_target`, `invalid_headers`, `invalid_body`, `invalid_content_rules`, `keyword_needs_rule`, `invalid_method`; `invalid` (`field`) for a value of the wrong type.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/monitors/{id}

Delete a monitor

Deletes the monitor with its history, events and incidents.

Parameters

idpath · requiredMonitor id.

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/monitors/{id}/mute

Mute a monitor

Suppresses down detection and alerts for `minutes` (capped at 7 days). 0 clears the mute. Returns the updated monitor.

Parameters

idpath · requiredMonitor id.

Request body · MuteInput

Field	Type	Description
`minutes`req	number \| null

Responses

200UpdatedMonitor
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422Validation failed. The `error` code names the field or rule.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/heartbeats/{id}/pingNo auth

Heartbeat check-in

Call this from your job. No auth: the monitor id is the secret. GET and POST both work, so a bare `curl` does. A ping that lands well before the next one is due is deduplicated.

Parameters

idpath · requiredHeartbeat monitor id.

Responses

200Ping recorded (`deduped: true` when it was ignored as a duplicate)Pinged
404`not_found`: not a heartbeat monitor, or it is paused.Error

post/v1/heartbeats/{id}/pingNo auth

Heartbeat check-in

Call this from your job. No auth: the monitor id is the secret. GET and POST both work, so a bare `curl` does. A ping that lands well before the next one is due is deduplicated.

Parameters

idpath · requiredHeartbeat monitor id.

Responses

200Ping recorded (`deduped: true` when it was ignored as a duplicate)Pinged
404`not_found`: not a heartbeat monitor, or it is paused.Error

get/v1/monitors/{id}/history

Chart data

Latency and uptime series over the last `range` hours, derived from hourly rollups. The window is clamped to the owner's plan retention (free 7d, pro 30d, team 90d).

Parameters

idpath · requiredMonitor id.
rangequeryHours to cover. Default 48; clamped to the plan's retention.

Responses

200OKHistory
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Events

get/v1/monitors/{id}/events

A monitor's activity

Status changes and user actions, newest first, within the owner's plan retention.

Parameters

idpath · requiredMonitor id.
limitqueryRows to return (1 to 200). Default 50.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/events

Activity across monitors

Status changes (only) across every monitor the credential can see, newest first, each tagged with `monitor_id` and `monitor_name`.

Parameters

limitqueryRows to return (1 to 200). Default 100.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Incidents

get/v1/incidents

Incident feed

Incidents across every monitor the credential can see, ongoing first then newest. `project` narrows it to one project.

Parameters

projectqueryProject ref to narrow the feed to.
limitqueryRows to return (1 to 200). Default 100.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required`: incidents are a paid feature and the project owner is on the free plan.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/monitors/{id}/incidents

A monitor's incidents

Ongoing first, then newest.

Parameters

idpath · requiredMonitor id.
limitqueryRows to return (1 to 200). Default 50.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/monitors/{id}/coverage

Is the monitor under maintenance or in an incident

Parameters

idpath · requiredMonitor id.

Responses

200OKCoverage
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects/{ref}/incidents

Declare a manual incident

Opens an incident the checks did not catch, spanning one or more of the project's monitors. Owner or admin. Manual incidents are closed by a `resolved` update, never automatically.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · IncidentInput

Field	Type	Description
`title`req	string
`severity`req	string	`degraded_performancepartial_outagemajor_outage`
`monitor_ids`req	string[]	Monitors in this project. Ids from other projects are dropped; `invalid_monitors` if none remain.
`body`	string	Text of the opening update.

Responses

201Created
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required`: the project owner is on the free plan. `forbidden`: the caller is not an owner or admin.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid`: missing title, severity or monitors. `invalid_monitors`: none of the ids belong to the project.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/incidents/{id}

Get an incident

One incident with its full update timeline (including `author_id`) and postmortem.

Parameters

idpath · requiredIncident id.

Responses

200OKIncident
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/incidents/{id}

Set the postmortem

Owner or admin of the incident's project. An empty string clears it.

Parameters

idpath · requiredIncident id.

Request body · PostmortemInput

Field	Type	Description
`postmortem`req	string

Responses

200Saved
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`forbidden`: not an owner or admin.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid`: `postmortem` is not a string.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/incidents/{id}

Delete an incident

Owner or admin. Removes the incident with its updates.

Parameters

idpath · requiredIncident id.

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`forbidden`: not an owner or admin.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/incidents/{id}/updates

Post an update

Adds to the timeline and applies the new `status` and/or `severity` to the incident. A `resolved` status closes it. Owner or admin. At least one field is required.

Parameters

idpath · requiredIncident id.

Request body · IncidentUpdateInput

Field	Type	Description
`status`	string	`detectedinvestigatingidentifiedmonitoringresolved`
`severity`	string	`degraded_performancepartial_outagemajor_outage`
`body`	string

Responses

201PostedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`forbidden`: not an owner or admin.Error
404`not_found`: no such object, or the key's project cannot see it.Error
409`incident_resolved`: the incident is closed and takes no more updates.Error
422`invalid`: no status, severity or body.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/incidents/{id}/ack

Acknowledge an incident

Halts escalation; the incident stays open until it recovers or is resolved. Anyone who can see the monitor. Idempotent: the first ack wins.

Parameters

idpath · requiredIncident id.

Responses

200AcknowledgedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/projects/{ref}/incident-policy

Get the incident policy

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OKIncidentPolicy
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/projects/{ref}/incident-policy

Update the incident policy

Owner or admin. Only the fields sent are changed; values outside 0 to 1440 are ignored.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · IncidentPolicyPatch

Field	Type	Description
`open_after_min`	integer	Minutes a monitor must stay down before an incident opens (and the public status flips, and alerts fire).
`close_grace_min`	integer	Minutes recovery must hold before the incident closes.
`trigger`	string	Whether `slow` also counts toward opening an incident.`downdown_slow`

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`forbidden`: not an owner or admin.Error
422`invalid`: nothing valid to change.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Channels

get/v1/projects/{ref}/channels

List a project's channels

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects/{ref}/channels

Add a channel

One channel per provider per project. Owner or admin. Email channels are paid; the webhook family (slack, discord, telegram, webhook) is free.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · ChannelInput

Field	Type	Description
`provider`req	string	`slackdiscordtelegramwebhookemail`
`name`req	string
`url`req	string	The destination: an https webhook URL, or the mailbox for `email`.

Responses

201CreatedChannel
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: email_alerts`): an email channel on a free-plan project.Error
404`not_found`: no such object, or the key's project cannot see it.Error
409`channel_exists`: the project already has a channel for this provider.Error
422`invalid_provider`, `invalid_name`, `invalid_url`, `invalid_email`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/channels/{id}

Update a channel

Owner or admin. Only the fields sent are changed.

Parameters

idpath · requiredChannel id.

Request body · ChannelPatch

Field	Type	Description
`name`	string
`enabled`	boolean
`url`	string	Replacement destination; must match the channel's provider.
`events`	any
`monitor_ids`	string[] \| null	null: the whole project. An array: exactly these monitors (an empty array covers none).

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_url`, `invalid_email`, `invalid_monitor_ids`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/channels/{id}

Delete a channel

Parameters

idpath · requiredChannel id.

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/channels/{id}/test

Send a test alert

Delivers a sample message to the destination. Owner or admin.

Parameters

idpath · requiredChannel id.

Responses

200Delivery attempted: `ok` says whether the destination accepted it, `status` is its HTTP response code when there was one
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: email_alerts`): an email channel on a free-plan project.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/projects/{ref}/alert-prefs

Get the project's alert overrides

Which transitions alert for this project (`prefs`) and the owner's account defaults they fall back to (`account`).

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/projects/{ref}/alert-prefs

Set the project's alert overrides

Owner or admin. true/false pins an event for the project, null clears the override so it follows the account again. An event not sent is left alone.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · ProjectAlertPrefsPatch

Field	Type	Description
`down`	boolean \| null	true/false pins the event for this project; null follows the account default.
`slow`	boolean \| null	true/false pins the event for this project; null follows the account default.
`recovery`	boolean \| null	true/false pins the event for this project; null follows the account default.

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such project, not an owner or admin, or nothing to change.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Maintenance

get/v1/projects/{ref}/maintenance

List maintenance windows

Newest window first. While a window is active the covered monitors are not checked and raise no alerts or incidents.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects/{ref}/maintenance

Schedule a window

Owner or admin. Active or scheduled windows per project are capped by the owner's plan (free 1, pro 10, team unlimited).

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · MaintenanceInput

Field	Type	Description
`title`req	string
`description`	string
`start_at`req	integer	Start. Epoch milliseconds.
`end_at`req	integer	End. Must be after `start_at` (`invalid_window`). Epoch milliseconds.
`recurrence`	any
`monitor_ids`	string[]	Monitors to cover. Omit or send [] to cover the whole project.

Responses

201CreatedMaintenance
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: maintenance`, `limit`): the plan's active-window cap is reached.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_name`, `invalid_window`, `invalid_recurrence`, `invalid_monitor_ids`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/maintenance/{id}

Update a window

Owner or admin. `description`, `recurrence` and `monitor_ids` replace when present; omit a field to leave it alone.

Parameters

idpath · requiredMaintenance window id.

Request body · MaintenancePatch

Field	Type	Description
`title`	string
`description`	string \| null	Present replaces (null clears); absent leaves it alone.
`start_at`	integer
`end_at`	integer
`recurrence`	any
`monitor_ids`	string[]	Present replaces; absent leaves it alone.

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_window`, `invalid_recurrence`, `invalid_monitor_ids`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/maintenance/{id}

Delete a window

Parameters

idpath · requiredMaintenance window id.

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Status pages

get/v1/projects/{ref}/status-page

Get the project's status page

The page's configuration, or null when the project has none.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OKStatusPage
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required`: status pages are a paid feature and the project owner is on the free plan.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects/{ref}/status-page

Create the status page

One per project. Owner or admin. The page starts public with a vanity subdomain derived from its name.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · StatusPageInput

Field	Type	Description
`name`req	string
`description`	string

Responses

201CreatedStatusPage
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required`: status pages are a paid feature and the project owner is on the free plan.Error
404`not_found`: no such object, or the key's project cannot see it.Error
409`status_page_exists`: the project already has one.Error
422`invalid_name`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/status-pages/{id}

Update a status page

Owner or admin. Only the fields sent are changed.

Parameters

idpath · requiredStatus page id.

Request body · StatusPagePatch

Field	Type	Description
`name`	string
`description`	string
`is_public`	boolean
`logo_url`	string \| null	null or empty clears it.
`brand_color`	string \| null	null or empty clears it.
`uptime_days`	integer
`show_uptime`	boolean
`subdomain`	string	New vanity handle (`invalid_subdomain` if malformed or reserved, `subdomain_taken` if in use).

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
409`subdomain_taken`.Error
422`invalid_subdomain`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/status-pages/{id}

Delete a status page

Parameters

idpath · requiredStatus page id.

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

put/v1/status-pages/{id}/monitors

Choose the monitors shown

Replaces the selection; array order is display order. Monitors outside the page's project are dropped. An empty list shows every enabled monitor in the project.

Parameters

idpath · requiredStatus page id.

Request body · StatusPageMonitorsInput

Field	Type	Description
`monitors`req	object[]

Responses

200SavedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/status-pages/{id}/domain

Re-check the custom domain

Dashboard-only: an API key is refused with `403 session_required`. Polls issuance and returns the current state.

Parameters

idpath · requiredStatus page id.

Responses

200OKDomainStatus
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error
502`cf_unreachable`, `cf_error`.Error
503`domain_unconfigured`.Error

post/v1/status-pages/{id}/domain

Connect a custom domain

Dashboard-only: an API key is refused with `403 session_required`. Registers the domain for the page and returns the CNAME target to point it at. Custom domains per account are capped by plan (free 0, pro 1, team 3).

Parameters

idpath · requiredStatus page id.

Request body · DomainInput

Field	Type	Description
`domain`req	string

Responses

200Registered; issuance is `pending` until the CNAME resolvesDomainStatus
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: called with an API key. `plan_required`: the plan allows no custom domain. `domain_limit`: the plan's cap is reached.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_domain`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error
502`cf_unreachable`, `cf_error`: the certificate provider did not answer.Error
503`domain_unconfigured`: custom domains are not set up on this deployment.Error

delete/v1/status-pages/{id}/domain

Disconnect the custom domain

Dashboard-only: an API key is refused with `403 session_required`.

Parameters

idpath · requiredStatus page id.

Responses

200DisconnectedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Escalation

get/v1/projects/{ref}/escalation

Get the on-call escalation policy

Team plan. Any project member may read it.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OKEscalationPolicy
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: escalation`): the project owner is not on the Team plan.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

put/v1/projects/{ref}/escalation

Replace the escalation policy

Team plan. Owner or admin. The whole policy is replaced; every target must belong to the project.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · EscalationPolicyInput

Field	Type	Description
`enabled`req	boolean
`repeat_min`req	integer
`steps`req	object[]	In order, at most 10. Enabling with no steps is `invalid` (`field: enabled`).

Responses

200SavedEscalationPolicy
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`plan_required` (`feature: escalation`): the project owner is not on the Team plan.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid` with `field`: `steps` (too many), `enabled` (enabled with no steps), `target_type`, `target_id` (not in this project), `delay_min`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Projects

get/v1/projects

List projects

Dashboard-only: an API key is refused with `403 session_required`. Every project the account owns or is a member of, with status counts.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects

Create a project

Dashboard-only: an API key is refused with `403 session_required`. Projects per account are capped by plan (free 1, pro 3, team 5).

Request body · ProjectInput

Field	Type	Description
`name`req	string

Responses

201Created (without the count fields)Project
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: called with an API key. `project_limit` (`limit`): the plan's cap is reached.Error
422`invalid_name`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/projects/{ref}

Rename a project

Dashboard-only: an API key is refused with `403 session_required`. Owner only.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · ProjectInput

Field	Type	Description
`name`req	string

Responses

200RenamedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_name`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/projects/{ref}

Delete a project

Dashboard-only: an API key is refused with `403 session_required`. Owner only. Deletes the project and everything in it, its monitors included, with their history and incidents.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200DeletedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Tokens

get/v1/tokens

List API keys

Dashboard-only: an API key is refused with `403 session_required`. The caller's own keys, metadata only.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/tokens

Create an API key

Dashboard-only: an API key is refused with `403 session_required`. Keys are minted from the dashboard so a leaked key can never mint more. The caller must be an owner, admin or member of the project; viewers cannot mint.

Request body · TokenInput

Field	Type	Description
`project_id`req	string	The one project the key will be scoped to.
`name`req	string	Label shown in the key list.
`ttl_seconds`	integer	Lifetime, clamped to 60 to 7,776,000 (90 days). Omit for a key that never expires.

Responses

201Created; the plaintext key is returned onceTokenCreated
400`project_required`: no `project_id`, or no write role on it. `name_required`.Error
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/tokens/{id}

Revoke an API key

Dashboard-only: an API key is refused with `403 session_required`.

Parameters

idpath · requiredToken id.

Responses

200RevokedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Team

get/v1/projects/{ref}/members

List members

Dashboard-only: an API key is refused with `403 session_required`. Owner first. Any member may read the roster.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

patch/v1/projects/{ref}/members/{userId}

Change a member's role

Dashboard-only: an API key is refused with `403 session_required`. Owner or admin.

Parameters

refpath · requiredProject ref.
userIdpath · requiredThe member's user id.

Request body · RoleInput

Field	Type	Description
`role`req	string	`adminmemberviewer`

Responses

200UpdatedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
422`invalid_role`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/projects/{ref}/members/{userId}

Remove a member

Dashboard-only: an API key is refused with `403 session_required`. Owner or admin; a member may remove themselves.

Parameters

refpath · requiredProject ref.
userIdpath · requiredThe member's user id.

Responses

200RemovedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

get/v1/projects/{ref}/invites

List pending invites

Dashboard-only: an API key is refused with `403 session_required`. Owner or admin.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/projects/{ref}/invites

Invite by email

Dashboard-only: an API key is refused with `403 session_required`. Owner or admin. Sends the invite email; the recipient's account email must match to accept.

Parameters

refpath · requiredProject ref (the `id` from GET /v1/projects).

Request body · InviteInput

Field	Type	Description
`email`req	string
`role`req	string	`adminmemberviewer`
`origin`	string	Dashboard origin to build the accept link from.

Responses

201Sent
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: called with an API key. `plan_required`: the project owner's plan has no team seats.Error
404`not_found`: no such object, or the key's project cannot see it.Error
409`already_member`, `seat_limit`.Error
422`invalid_email`, `invalid_role`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

delete/v1/invites/{id}

Revoke an invite

Dashboard-only: an API key is refused with `403 session_required`. Owner or admin.

Parameters

idpath · requiredInvite id.

Responses

200RevokedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: no such object, or the key's project cannot see it.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/invites/accept

Accept an invite

Dashboard-only: an API key is refused with `403 session_required`. The signed-in account's email must match the invited address.

Request body · InviteAcceptInput

Field	Type	Description
`token`req	string	The token from the invite link.

Responses

200Joined
400`invalid_invite`.Error
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: called with an API key. `email_mismatch`: the account's email is not the invited one.Error
409`already_member`.Error
410`invite_expired`.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Connectors

get/v1/connectors

List connected providers

Dashboard-only: an API key is refused with `403 session_required`. Paid feature.

Responses

200OK
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: called with an API key. `plan_required`: the account is on the free plan.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

post/v1/connectors/{provider}/oauth/start

Begin the OAuth connect flow

Dashboard-only: an API key is refused with `403 session_required`.

Parameters

providerpath · required

Responses

200Open this URL to authorize
400`unknown_provider`, or an OAuth error code.Error
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error
503`provider_unconfigured`.Error

get/v1/connectors/{provider}/projects

List a provider's projects

Dashboard-only: an API key is refused with `403 session_required`. Live from the provider, flagging the ones already imported.

Parameters

providerpath · required

Responses

200OK
400`unknown_provider`. `invalid_token`: the provider rejected the stored token; reconnect.Error
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: not connected.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error
502`connector_unavailable`: the provider did not answer.Error

post/v1/connectors/{provider}/import

Import projects as monitors

Dashboard-only: an API key is refused with `403 session_required`. Already-imported refs are skipped; per-project failures (such as the monitor cap) are listed in `failed` rather than failing the batch.

Parameters

providerpath · required

Request body · ImportInput

Field	Type	Description
`external_refs`req	string[]
`project_id`	string	Project to import the monitors into.

Responses

200Import resultImportResult
400`unknown_provider`, `invalid_token`.Error
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: not connected.Error
422`no_projects`: `external_refs` is empty.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error
502`connector_unavailable`.Error

delete/v1/connectors/{provider}

Disconnect a provider

Dashboard-only: an API key is refused with `403 session_required`.

Parameters

providerpath · required

Responses

200DisconnectedOk
401`unauthorized`: the `Authorization` header is missing, or the token is invalid, expired or revoked.Error
403`session_required`: this route is dashboard-only and was called with an API key.Error
404`not_found`: not connected.Error
429`rate_limited`: API-key requests are pooled per account across all its projects and keys, per minute (free 30, pro 120, team 300). Dashboard sessions are not limited. Wait `Retry-After` seconds.Error

Prefer the raw document? It's served straight from the API at /openapi.json.