API base and specification#
Use your deployment's API origin, not the public documentation site's URL. Paths below are relative to that origin. The OpenAPI document is available as an API specification download. It describes implemented contracts but is not a promise that every current administration field is exhaustively modeled.
Authentication#
Password sign-in posts organization, email and password to /v1/auth/login and returns a bearer token with its expiry. Authenticated calls use Authorization: Bearer TOKEN. Store tokens securely, observe expiry/revocation, and do not put them in query strings. The Web UI uses a server-side cookie proxy rather than exposing its bearer token to browser storage.
{
"organization": "your-organization-slug",
"email": "responder@example.internal",
"password": "YOUR_PASSWORD"
}API keys and service accounts#
For scripts, CI and other systems, use an API key instead of a person's session. Organization administrators manage keys under API Keys in Administer, and each person can manage their own personal keys. Send the key as Authorization: Bearer YOUR_API_KEY.
| Kind | Acts as | Role |
|---|---|---|
| Personal | The person who created it. | Never higher than the owner's current role. |
| Organization | A dedicated service account named after the key, so its actions are attributed to the key by name. | Exactly the role chosen when the key was created. |
- The token is shown once at creation; only its hash is stored. Expiry is optional, from 1 to 730 days.
- An organization can have at most 50 active organization keys, and each person at most 10 active personal keys.
- A service account cannot sign in, and is left out of people pickers, on-call candidates, call routing, reports and postmortem owners. Revoking the key deactivates it.
- Whatever its role, a key cannot create API keys, generate a SCIM token, change notification rules or contact details, create a calendar feed link or register a push device; those need a signed-in session.
- Creation and revocation are audited with the key name and prefix, never the token. A revoked or expired key, or one whose owner is deactivated, gets 401.
Core endpoints#
| Method and path | Purpose |
|---|---|
| GET /v1/me | Inspect the authenticated principal. |
| GET /v1/incidents | List organization incidents; status filtering is available. |
| GET /v1/incidents/{id} | Read incident, timeline, and operational context. |
| POST /v1/incidents/{id}/acknowledge | Acknowledge using the current version. |
| POST /v1/incidents/{id}/resolve | Resolve with the current version and reason. |
| GET /v1/alerts | Inspect normalized alerts. |
| GET /v1/on-call | Inspect effective on-call information. |
| GET /v1/events | Authenticated server-sent incident events. |
| POST /v1/incidents/{id}/notes | Add a note; notify_stakeholders posts it as a stakeholder update. |
| POST /v1/incidents/{id}/status-updates | Publish a status page update. |
| POST /v1/incidents/{id}/ticket | Open a ticket on a ticketing connection. |
| GET / PUT /v1/incidents/{id}/postmortem | Read or write the incident's postmortem. |
| GET / POST /v1/maintenance | List or schedule maintenance windows. |
| POST /integrations/webhook/{id} | Accept a separately authenticated monitoring payload. |
| POST /v2/enqueue | Accept a PagerDuty Events API v2 compatible event. |
| GET, POST or HEAD /heartbeat/{token} | Record a heartbeat ping. |
| /scim/v2 | SCIM 2.0 provisioning, authenticated with the organization's SCIM token. |
Version-aware response#
{ "version": 7 }The example is an acknowledge request. Read the actual current incident version; do not hardcode it. Resolution additionally accepts a reason. If a concurrent change causes 409, refresh and reassess before resubmitting.
Administration endpoints#
The /v1/admin routes require organization_admin. Resource areas include organization, users, teams, services, schedules, policies, integrations, routing-rules, providers, audit, api-keys, status-pages, call-routes, ticketing, webhooks and scim. Integration tests, provider tests and onboarding completion have separate actions. Do not infer a supported HTTP verb merely from a resource name.
| Action | Endpoint |
|---|---|
| Create integration | POST /v1/admin/integrations |
| Rotate webhook secret | POST /v1/admin/integrations/{id}/rotate |
| Send integration test | POST /v1/admin/integrations/{id}/test |
| Save provider | PUT /v1/admin/providers/{channel} |
| Test provider | POST /v1/admin/providers/{channel}/test |
| Create API key | POST /v1/admin/api-keys |
| Export audit log | GET /v1/admin/audit/export?from=&to=&format= |
| Configure audit stream | PUT /v1/admin/audit/sink |
| Delivery health | GET /v1/operations |
| Retry dead letter | POST /v1/operations/dead-letters/{id}/retry |
Error handling#
| Response | Interpretation |
|---|---|
| 202 | Webhook accepted durably, not necessarily processed/delivered. |
| 400 | Invalid input; inspect the documented request shape. |
| 401 / 403 | Invalid authentication or insufficient authorization. |
| 404 | Resource unavailable in this authorized scope or path not found. |
| 409 | State/version or configuration conflict; refresh and investigate. |
| 429 | Throttled; honor Retry-After when provided. |
| 503 | A required service or processing dependency is unavailable. |
Automation rules#
- Reuse an idempotency key only for retries of the same integration event.
- Use bounded backoff and distinguish a failed response from an ambiguous committed request.
- Do not log bearer tokens, webhook keys, provider configuration, or raw customer payloads by default.
- Some listing endpoints are bounded, not exhaustive paginated exports. Validate coverage before using them for reporting.
- Test API clients against the exact deployed release; the schema download is a reference, not a hosted API service.