A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The PagerDuty API is how an app or AI agent works with an on-call account: listing and creating incidents, acknowledging or resolving them, adding notes, and reading who is on call across schedules and escalation policies. Access is granted through an API token or an OAuth token, and a scoped OAuth token carries per-resource read or write scopes that set which resources a call can touch. A separate events route opens and closes incidents using a per-service key, and a state change can be pushed to a registered subscription.
How an app or AI agent connects to PagerDuty determines what it can reach. There is a route for reading and changing accounts, a separate route for sending events that open and close incidents, and a hosted server that exposes PagerDuty tools to agents, and each is governed by the token behind it and the scopes that token carries.
The REST API takes and returns JSON at https://api.pagerduty.com, and pins the response shape with the Accept header application/vnd.pagerduty+json;version=2. A call authenticates with an account API token or a user OAuth token sent as Authorization: Token token=... or Bearer. Writes that act on a user's behalf, like creating an incident, also need a From header naming a valid user. Lists page with limit and offset by default, and some endpoints use a cursor.
The Events API opens, acknowledges, and resolves incidents by POSTing a JSON event to https://events.pagerduty.com/v2/enqueue, and records deploys at /v2/change/enqueue. It authenticates with a 32-character integration routing key tied to one service, not an account token, so a sender can only affect that service. The event_action field is trigger, acknowledge, or resolve, and a dedup_key correlates the three for the same alert.
PagerDuty publishes a first-party Model Context Protocol server that exposes PagerDuty tools to AI agents and clients like Claude Desktop, Cursor, and VS Code. A hosted, OAuth-based remote server runs at mcp.pagerduty.com/mcp with no local install, and an open-source build runs locally via uvx or Docker with a user API token. It exposes tools for incidents, services, schedules, on-calls, escalation policies, teams, users, and event orchestrations. By default only read tools are available; write tools are off unless the server is started with the --enable-write-tools flag.
PagerDuty POSTs event payloads to an HTTPS endpoint registered as a V3 webhook subscription, created in the web app or via POST /webhook_subscriptions. A subscription is filtered to a service, team, or the whole account and lists the exact event types it wants. The receiver verifies the X-PagerDuty-Signature header against the subscription's signing secret to confirm the request came from PagerDuty.
An account-level REST API key acts for the whole account and is not tied to a person. A read-write key can call every endpoint; a read-only key is limited to GET requests. Writes that act on a user's behalf still require a From header naming a valid user. The key is sent as Authorization: Token token=
A user-level REST API key inherits that user's permissions and abilities, so its reach matches what the person can do. It is sent the same way as an account key and is the token used to call user-specific endpoints like the current user.
Scoped OAuth issues a token that carries granular read or write scopes per resource, like incidents.read or incidents.write. A GET needs the resource's read scope and a PUT, POST, or DELETE needs its write scope; a call missing the required scope returns 403. This is the route for an app to reach only the resources it was granted.
The Events API authenticates with a 32-character integration routing key tied to a single service, not an account token. A holder can only open and close incidents on that one service, which keeps a leaked key contained to one service rather than the whole account.
The PagerDuty API is split into areas an agent can act on, like incidents, services, schedules, escalation policies, users, teams, and on-calls. Each area has its own methods, and writes in some areas change who gets paged and when.
Methods for listing, getting, creating, and managing incidents and their notes.
Methods for working with services, the things PagerDuty monitors.
Methods for working with on-call schedules and overrides.
Methods for working with escalation policies, the rules for who gets paged next.
Methods for working with the people in an account.
Methods for working with teams and their membership.
Methods for reading who is currently on call.
Methods for opening and closing incidents by sending events with a routing key.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
IncidentsMethods for listing, getting, creating, and managing incidents and their notes.8 | ||||||
| GET | /incidents | List incidents, filtered by status, service, team, urgency, or date range. | read | incidents.read | Current | |
Read-only. Scoped OAuth requires incidents.read. Acts onincident Permission (capability) incidents.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /incidents/{id} | Get the details of a single incident by its id or number. | read | incidents.read | Current | |
Read-only. Acts onincident Permission (capability) incidents.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /incidents | Create an incident on a service, optionally setting urgency, priority, and assignment. | write | incidents.write | Current | |
Requires a From header set to a valid user's email. Pages the on-call responder. Acts onincident Permission (capability) incidents.writeVersionAvailable since the API’s base version Webhook event incident.triggeredRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /incidents/{id} | Update a single incident: change status, urgency, priority, assignment, or escalation level. | write | incidents.write | Current | |
Requires a From header. Setting status to acknowledged or resolved fires the matching webhook. Acts onincident Permission (capability) incidents.writeVersionAvailable since the API’s base version Webhook event incident.acknowledgedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /incidents | Acknowledge or resolve many incidents in one request. | write | incidents.write | Current | |
Requires a From header. Bulk status changes across up to a set number of incidents per call. Acts onincident Permission (capability) incidents.writeVersionAvailable since the API’s base version Webhook event incident.resolvedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /incidents/{id}/notes | List the notes attached to an incident. | read | incidents.read | Current | |
Read-only. Acts onincident_note Permission (capability) incidents.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /incidents/{id}/notes | Add a note to an incident. | write | incidents.write | Current | |
Requires a From header set to a valid user's email. Acts onincident_note Permission (capability) incidents.writeVersionAvailable since the API’s base version Webhook event incident.annotatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /incidents/{id}/alerts | List the alerts that make up an incident. | read | incidents.read | Current | |
Read-only. Acts onalert Permission (capability) incidents.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ServicesMethods for working with services, the things PagerDuty monitors.4 | ||||||
| GET | /services | List services in the account, optionally filtered by team or name. | read | services.read | Current | |
Read-only. Acts onservice Permission (capability) services.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/{id} | Get the details of a single service. | read | services.read | Current | |
Read-only. Acts onservice Permission (capability) services.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services | Create a service, attaching it to an escalation policy. | write | services.write | Current | |
A core configuration write. Acts onservice Permission (capability) services.writeVersionAvailable since the API’s base version Webhook event service.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /services/{id} | Update a service, such as its escalation policy or alert grouping. | write | services.write | Current | |
Changes how the service triggers and routes incidents. Acts onservice Permission (capability) services.writeVersionAvailable since the API’s base version Webhook event service.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SchedulesMethods for working with on-call schedules and overrides.3 | ||||||
| GET | /schedules | List on-call schedules in the account. | read | schedules.read | Current | |
Read-only. Acts onschedule Permission (capability) schedules.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /schedules/{id} | Get a schedule, with the rendered on-call rotation for a time range. | read | schedules.read | Current | |
Read-only. Acts onschedule Permission (capability) schedules.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /schedules/{id}/overrides | Create an override so a different user is on call for a period. | write | schedules.write | Current | |
Changes who is paged during the override window. Acts onoverride Permission (capability) schedules.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Escalation PoliciesMethods for working with escalation policies, the rules for who gets paged next.3 | ||||||
| GET | /escalation_policies | List escalation policies in the account. | read | escalation_policies.read | Current | |
Read-only. Acts onescalation_policy Permission (capability) escalation_policies.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /escalation_policies/{id} | Get a single escalation policy and its rules. | read | escalation_policies.read | Current | |
Read-only. Acts onescalation_policy Permission (capability) escalation_policies.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /escalation_policies | Create an escalation policy defining who is paged and in what order. | write | escalation_policies.write | Current | |
Defines the chain of responders an incident escalates through. Acts onescalation_policy Permission (capability) escalation_policies.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersMethods for working with the people in an account.4 | ||||||
| GET | /users | List users in the account. | read | users.read | Current | |
Read-only. Acts onuser Permission (capability) users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{id} | Get a single user, including contact methods if requested. | read | users.read | Current | |
Read-only. Acts onuser Permission (capability) users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/me | Get the user associated with the current user OAuth token. | read | users.read | Current | |
Read-only. Only works with a user-level OAuth token, not an account API key. Acts onuser Permission (capability) users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Create a user in the account. | write | users.write | Current | |
Requires a From header set to an admin user's email. Acts onuser Permission (capability) users.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsMethods for working with teams and their membership.3 | ||||||
| GET | /teams | List teams in the account. | read | teams.read | Current | |
Read-only. Acts onteam Permission (capability) teams.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /teams | Create a team. | write | teams.write | Current | |
A core configuration write. Acts onteam Permission (capability) teams.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /teams/{id}/users/{user_id} | Add a user to a team, optionally setting their role on it. | write | teams.write | Current | |
Changes what the user can see and be paged for. Acts onteam_membership Permission (capability) teams.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
On-CallsMethods for reading who is currently on call.1 | ||||||
| GET | /oncalls | List who is on call now and ahead, by user, schedule, escalation policy, or time range. | read | oncalls.read | Current | |
Read-only. Resolves schedules and overrides into the actual on-call people. Acts ononcall Permission (capability) oncalls.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Events APIMethods for opening and closing incidents by sending events with a routing key.2 | ||||||
| POST | https://events.pagerduty.com/v2/enqueue | Send an alert event to trigger, acknowledge, or resolve an incident using a routing key. | write | Integration routing key | Current | |
Authenticated by the service's routing key, not an account token. event_action is trigger, acknowledge, or resolve; dedup_key correlates the three. Acts onevent Permission (capability) Integration routing keyVersionAvailable since the API’s base version Webhook event incident.triggeredRate limitDynamic per-service limit SourceOfficial documentation ↗ | ||||||
| POST | https://events.pagerduty.com/v2/change/enqueue | Send a change event to record a deploy or configuration change against a service. | write | Integration routing key | Current | |
Authenticated by the service's routing key. Change events are informational and do not page anyone. Acts onchange_event Permission (capability) Integration routing keyVersionAvailable since the API’s base version Webhook eventNone Rate limitDynamic per-service limit SourceOfficial documentation ↗ | ||||||
PagerDuty can notify an app when something happens in an account, like an incident being triggered, acknowledged, or resolved. A V3 webhook subscription sends the chosen event types to a registered endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
incident.triggered | An incident was created and is active, by an event or a create call. The point where the on-call responder is paged. | /incidentshttps://events.pagerduty.com/v2/enqueue |
incident.acknowledged | An incident was acknowledged by a responder, pausing further escalation. | /incidents/{id}/incidentshttps://events.pagerduty.com/v2/enqueue |
incident.resolved | An incident was resolved and closed. | /incidents/{id}/incidentshttps://events.pagerduty.com/v2/enqueue |
incident.annotated | A note was added to an incident. | /incidents/{id}/notes |
incident.escalated | An incident escalated to the next level of its escalation policy. | /incidents/{id} |
incident.reassigned | An incident was reassigned to a different responder. | /incidents/{id} |
service.created | A new service was created in the account. | /services |
service.updated | A service was updated, such as its escalation policy or settings. | /services/{id} |
PagerDuty limits how fast an app can call. The REST API counts requests per minute against the token making them, and the Events API that opens and closes incidents is metered separately and adjusts dynamically.
The REST API allows 960 requests per minute. The count is kept three ways at once: per account API key, per user across all of that user's keys, and per PagerDuty app against each account it can access. Going over returns HTTP 429 with ratelimit-limit, ratelimit-remaining, and ratelimit-reset response headers, where ratelimit-reset is the number of seconds to wait before retrying. The Events API that opens and closes incidents is metered separately and adjusts dynamically based on incoming traffic, so a 429 there should be retried with backoff.
Most list endpoints use classic pagination with limit (the page size) and offset (where to start), and a more flag in the response signals whether further pages remain. The sum of limit and offset cannot exceed 10,000, or the call returns a 400. The total count is omitted by default for speed and only returned when total=true is passed. Some endpoints instead use cursor pagination, returning a next_cursor to pass on the following request.
Classic pagination caps limit at 100 per page and cannot reach beyond the 10,000th record. An Events API routing key is a 32-character string. A V3 webhook subscription is limited to a set number per service, team, or account scope.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | 2001 Invalid Input Provided | The request was malformed: a field is missing, an extra or wrong field name was sent, or a value is invalid. Classic pagination also returns 400 when limit plus offset exceeds 10,000. | Read the error message and the errors array, fix the request body or parameters, and resend. |
| 400 | 2002 Arguments Caused Error | The arguments were understood but produced an error when processed. | Inspect the errors array for the specific cause and correct the offending values. |
| 401 | Unauthorized | The request could not be authenticated. The token is missing, malformed, or invalid, or the Authorization header format is wrong. | Send a valid token as Authorization: Token token= |
| 402 | 2012 Account Expired | The account is expired or on a plan that cannot use this feature of the API. | Resolve the account or plan status before retrying. |
| 403 | 2010 Access Denied | The token authenticated but lacks the permission, ability, or OAuth scope for this request. Scoped OAuth returns 403 when the token is missing the required read or write scope. | Grant the needed scope or ability, or use a token with sufficient access. |
| 404 | 2100 Not Found | The requested resource does not exist or is not visible to this token. | Verify the id and confirm the resource exists in this account and is visible to the token. |
| 429 | Too Many Requests | A rate limit was hit. The response carries ratelimit-limit, ratelimit-remaining, and ratelimit-reset headers. | Wait the number of seconds in ratelimit-reset, then retry with backoff. Smooth the request rate. |
PagerDuty pins the REST API to version 2 through an Accept header rather than a path segment, and ships dated, mostly additive changes through its changelog.
The REST API is pinned to version 2 through the Accept header application/vnd.pagerduty+json;version=2 rather than a URL path segment. Changes are mostly additive and shipped through a dated changelog, so an integration that sends the versioned Accept header keeps stable responses as new fields and endpoints are added.
V3 webhook subscriptions became the way to receive events, letting a subscription choose exact event types and filter by service, team, or account, and verify payloads with the X-PagerDuty-Signature header. Older V2 generic webhook extensions are superseded.
Send the versioned Accept header on every call so responses stay stable as features are added.
PagerDuty API changelog ↗Bollard AI sits between a team's AI agents and PagerDuty. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.