Perstat
Overview
Perstat API 1.0.0-beta.1
Section titled “Perstat API 1.0.0-beta.1”The Perstat API gives you programmatic access to your monitoring data: monitors, incidents, status pages, maintenance windows, webhooks, and organization management.
Authentication
Authenticate with an API key as a Bearer token: create keys in your organization settings (API keys section) in the Perstat app, then send Authorization: Bearer pst_… with every request. Keys are organization-bound, carry explicit scopes (resource:read or resource:write, where write implies read), and can be narrowed to specific projects or monitors. All authenticated operations in this public specification accept API keys, marked with x-api-key-enabled and x-api-key-scope. The creator must still be a member with the role required by the operation; scopes never grant a higher role. Organization-wide resources require an unrestricted organization key. Project and monitor operations respect resource grants; project lists are filtered. Account login, billing and API-key management remain session-only and are outside this public contract. Creating another organization requires the separate org:create scope, an organization-wide key and a creator who is currently an owner. The key remains bound to its original organization and does not gain access to the new organization.
Stability
This specification is versioned independently of the product. Additive changes (new fields, new endpoints) can happen at any time; removals or renames only after a deprecation window of at least 90 days, announced in the changelog on perstat.io. During that window, successful answers to a deprecated call carry the Deprecation and Sunset headers (RFC 9745, RFC 8594) with a Link to the announcement, and a deprecated operation is marked deprecated. Operation ids are stable identifiers.
Webhooks
Outbound webhook deliveries are signed with an HMAC-SHA256 signature in the x-perstat-signature header (sha256=
Authentication
Section titled “Authentication”bearer
Section titled “bearer”Use an organization API key with the operation scope and resource grants. Current creator membership and role are checked on every request.
Security scheme type: http
Bearer format: API key (pst_...) or session token