Skip to content
perstatDocs

API

Scoped API keys give your pipelines the full REST API. Create keys in the app under Integrations, then API keys (owners and admins), and send them as a bearer token:

Authorization: Bearer pst_...

A key belongs to one organization and carries explicit scopes, each as :read or :write. You can narrow a key further to selected projects or to individual monitors. Revocation and expiry take effect on the next request.

What a key can do

Section titled “What a key can do”

Every authenticated operation in the public contract accepts API keys: 69 operations, 46 of them writes.

Area Operations Scopes
Monitors create, update, archive, restore, checks, time series monitors:read, monitors:write
Incidents create, acknowledge, resolve, notes, post-mortems, downtime curation incidents:read, incidents:write
Status pages create, update, archive, monitors, domains, access status-pages:read, status-pages:write
Maintenance windows create, update, cancel, delete maintenance:read, maintenance:write
Webhooks create, update, test, rotate secret, delete webhooks:read, webhooks:write
Projects create, list, rename, delete projects:read, projects:write
Organization rename, members, roles, invitations org:read, org:write
On-call current duty, roster, settings on-call:read, on-call:write
Host agents list, remove agents:read, agents:write

A write scope implies read on the same resource, never across resources. Six further operations serve public status pages, badges, feeds, logos, and subscriptions without any key.

Safeguards built into every key

Section titled “Safeguards built into every key”
  • A key acts with its creator’s role. The person who created the key must still be a member with the role the operation requires, and scopes never grant a higher role.
  • Organization-wide resources need an organization-wide key. A key narrowed to projects or monitors reaches exactly those, and project lists are filtered to match.
  • Creating another organization takes the separate org:create scope, an organization-wide key, and a creator who is currently an owner. The key stays bound to its original organization.
  • Key management stays in the browser session, together with account login and billing. A leaked key can use what its scopes allow and can never mint itself a successor.
  • Every successful write is recorded with the key and the person who created it.

Good to know

Section titled “Good to know”
  • Archive a retired service. POST /monitors/{monitor_id}/archive preserves its incidents, check history, SLA rollups and exclusion windows. It closes open incidents and stops their escalations. POST /monitors/{monitor_id}/restore brings the monitor back paused and requires a free plan slot. Enable it explicitly when it is ready to resume checks.
  • Restore before editing. Updating an archived monitor returns 409 monitor_archived. In MCP, list_monitors with archived: true also lists the archive.
  • Deletion by API key is deprecated. Announced on 2 October 2026, with removal no earlier than 1 January 2027 at 00:00 UTC. Successful DELETE /monitors/{monitor_id} calls still delete permanently during the notice period and carry Deprecation, Sunset and Link headers. Migrate to the archive endpoint.
  • Move monitors before deleting a project. Pass reassign_to to DELETE /projects/{project_id} with a target project in the same organization that your key permits. Active and archived monitors move together with their records. Deletion by key without moving the monitors is deprecated with the same notice period. Empty projects remain deletable. The changelog records the announcement.
  • Intervals go down to your plan’s floor, including 15 s on Command and 10 s on Enterprise, and up to 24 hours. Values below the floor are raised to it. The web form offers 30 seconds to 1 hour.
  • The same keys work for MCP. The monitors and incidents scopes enable the matching MCP tools, and status-pages:read adds list_status_pages.

The full reference

Section titled “The full reference”

The reference documents all 75 operations across 54 paths of the public contract, version 1.0.0-beta.1.

The pages are generated at build time from the vendored contract. Each one carries its parameters, its request body, and every documented response, with the schemas expanded.

Browse the referenceAll 75 operations, grouped the way the product groups them: monitors, incidents, status pages, maintenance, webhooks, on-call, agents, and more.
Download the OpenAPI specThe same file the reference is generated from, version `1.0.0-beta.1`. Point your client generator, Postman, or an agent at it.

The product serves the spec at api.perstat.io/openapi.json. The copy here belongs to the build you are reading and generated these pages, while the product’s copy always matches what is deployed. When the two differ, the product is ahead.

The contract grows with the product. Additive changes such as new fields and endpoints can arrive at any time, and removals or renames follow a deprecation window of at least 90 days, announced in the changelog.