The PagerDuty REST API provides programmatic access to PagerDuty incidents, services, escalation policies, schedules, and users.
openapi: 3.0.2
info:
description: |
This document describes the PagerDuty REST APIs.
For guides and examples please visit our [Documentation.](https://developer.pagerduty.com/docs/get-started/getting-started/)
Our REST APIs are defined in OpenAPI v3.x. You can view the schema at [github.com/PagerDuty/api-schema](https://github.com/PagerDuty/api-schema).
Note that properties in some schemas have fields not shown by default such as `readOnly`, `format`, and `default`. Hover your cursor over the right column that looks like `optional+1` to see the full list of fields.
contact:
name: PagerDuty Support
url: http://www.pagerduty.com/support
email: [email protected]
title: PagerDuty API
version: 2.0.0
security:
- api_key: []
tags:
- name: Abilities
description: |
This describes your account's abilities by feature name. For example `"teams"`.
An ability may be available to your account based on things like your pricing plan or account state.
- name: Add-Ons
description: |
Developers can write their own functionality to insert into PagerDuty's UI.
- name: Alert Grouping Settings
description: |
Alert Grouping Settings allow you to configure how alerts in services are grouped together into incidents.
- name: Analytics
description: |
Provides enriched incident data.
- name: Audit
description: |
Provides audit record data.
- name: Automation Actions
description: |
Automation Actions invoke jobs that are staged in Runbook Automation or Process Automation.
- name: Business Services
description: |
Business services model capabilities that span multiple technical services and that may be owned by several different teams.
- name: Change Events
description: |
Change Events enable you to send informational events about recent changes such as code deploys and system config changes from any system that can make an outbound HTTP connection. These events do not create incidents and do not send notifications; they are shown in context with incidents on the same PagerDuty service.
- name: Custom Fields
description: |
Custom fields allow you to enrich PagerDuty incidents with critical and helpful metadata throughout the incident lifecycle.
- name: Escalation Policies
description: |
Escalation policies define which user should be alerted at which time.
- name: Event Orchestrations
description: |
Event Orchestrations allow you to route events to an endpoint and create collections of Event Orchestrations, which define sets of actions to take based on event content.
- name: Extension Schemas
description: |
A PagerDuty extension vendor represents a specific type of outbound extension such as Generic Webhook, Slack, ServiceNow.
- name: Extensions
description: |
Extensions are representations of Extension Schema objects that are attached to Services.
- name: Incident Workflows
description: |
An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident.
- name: Incidents
description: |
An incident represents a problem or an issue that needs to be addressed and resolved. Incidents trigger on a service, which prompts notifications to go out to on-call responders per the service's escalation policy.
- name: Licenses
description: |
Licenses are allocated to Users to allow for per-User access to PagerDuty functionality within an Account.
- name: Log Entries
description: |
A log of all the events that happen to an Incident, and these are exposed as Log Entries.
- name: Maintenance Windows
description: |
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
- name: Notifications
description: |
A Notification is created when an Incident is triggered or escalated.
- name: On-Calls
description: |
An on-call represents a contiguous unit of time for which a User will be on call for a given Escalation Policy and Escalation Rules
- name: Paused Incident Reports
description: |
Provides paused Incident reporting data on services and accounts that have paused Alerts.
- name: Priorities
description: |
A priority is a label representing the importance and impact of an incident. This feature is only available on Standard and Enterprise plans.
- name: Response Plays
description: |
Response Plays are a package of Incident Actions that can be applied during an Incident's life cycle.
- name: Rulesets
description: |
Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content.
- name: Schedules
description: |
A Schedule determines the time periods that users are On-Call.
- name: Service Dependencies
description: |
Services are categorized into technical and business services. Dependencies can be created via any combination of these services.
- name: Standards
description: |
Standards help provide a clear understanding of what a good service configuration looks like, allowing to share and enforce organization guidelines across services to ensure adherence to best practices.
- name: Status Dashboards
description: |
Status Dashboards represent user-defined views for the Status Dashboard product that are limited to specific Business Services rather than the whole set of top-level Business Services (those with no dependent Services).
- name: Status Pages
description: |
Status Pages can be public or private read-only pages, that display the status of some predefined set of services, to be shared with customers or internal stakeholders.
- name: Teams
description: |
A team is a collection of Users and Escalation Policies that represent a group of people within an organization.
- name: Templates
description: |
Templates is a new feature which will allow customers to create message templates to be leveraged by (but not limited to) status updates. The API will be secured to customers with the status updates entitlements.
- name: Users
description: |
Users are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.
- name: Vendors
description: |
A PagerDuty Vendor represents a specific type of integration. AWS Cloudwatch, Splunk, Datadog are all examples of vendors
- name: Webhooks
description: |
A webhook is a way to receive events that occur on the PagerDuty platform via an HTTP POST request.
V3 webhooks are set up by creating a webhook subscription.
servers:
- url: https://api.pagerduty.com
description: PagerDuty V2 API.
components:
examples:
AuditRecordResponse:
summary: Response Example
value:
records:
- id: PDRECORDID1_TEAM_CREATED
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 111lDEOIH-534-4ljhLHJjh111
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
method:
type: api_token
truncated_token: 3usr
root_resource:
id: PXASDFE
type: team_reference
summary: my DevOps team
action: create
details:
resource:
id: PXASDFE
type: team_reference
summary: my DevOps team
fields:
- name: teamName
value: DevOps team
- id: PDRECORDID2_USER_REMOVED_FROM_TEAM
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 222lDEOIH-534-4ljhLHJjh222
remote_address: 201.19.20.19
method:
type: api_token
truncated_token: 2adm
root_resource:
id: PRY9M8B
type: team_reference
summary: DevOps
action: update
details:
resource:
id: PRY9M8B
type: team_reference
summary: DevOps
references:
- name: members
removed:
- id: PRY9M8B
type: user_reference
summary: John Doe
- id: PDRECORDID5_USERS_TEAM_ROLE_UPDATED
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 222lDEOIH-534-4ljhLHJjh222
remote_address: 201.19.20.19
method:
type: api_token
truncated_token: 2adm
root_resource:
id: PRY9M8B
type: team_reference
summary: DevOps
action: update
details:
resource:
id: PDUSER
type: user_reference
summary: John Snow
fields:
- name: team_role
before_value: observer
value: manager
- id: PDRECORDID3_USERS_NAME_AND_EMAIL_UPDATED
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 222lDEOIH-534-4ljhLHJjh222
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
method:
type: identity_provider
root_resource:
id: PDUSER
type: user_reference
summary: John Snow
action: update
details:
resource:
id: PDUSER
type: user_reference
summary: John Snow
fields:
- name: name
before_value: Bob Doe
value: Jon Snow
- name: email
before_value: [email protected]
value: [email protected]
- id: PDRECORDID4_UPDATED_USERS_NOTIFICATION_RULE
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 222lDEOIH-534-4ljhLHJjh222
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
method:
type: api_token
truncated_token: 2adm
root_resource:
id: PDUSER
type: user_reference
summary: John Snow
action: update
details:
resource:
id: PXOGWUS
type: assignment_notification_rule_reference
summary: '0 minutes: channel P1IAAPZ'
fields:
- name: start_delay_in_minutes
before_value: '0'
value: '2'
references:
- name: contact_method
removed:
- id: POE6L88
type: push_notification_contact_method_reference
summary: Pixel 3
added:
- id: P4GTUMK
type: sms_contact_method_reference
summary: Mobile
next_cursor:
limit: 10
AuditRecordEscalationPolicyResponse:
summary: Response Example
value:
records:
- id: PD_ASSIGN_TEAM_TO_ESCALATION_POLICY
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
references:
- added:
- id: PD_TEAM123
summary: Devops
type: team_reference
self: https://api.pagerduty.com/teams/PD_TEAM123
html_url: https://mydomain.pagerduty.com/teams/PD_TEAM123
name: teams
resource:
id: PD_ESCALATION_ID
summary: DevOps Escalation
type: escalation_policy_reference
self: https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID
html_url: https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID
execution_context:
request_id: 0cc413fb-8e7d-4414-b4bc-b7578bf3ba77
execution_time: '2021-01-05T16:33:52.026Z'
method:
type: browser
root_resource:
id: PD_ESCALATION_ID
summary: DevOps Escalation
type: escalation_policy_reference
self: https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID
html_url: https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID
- id: PD_CREATE_ESCALATION_POLICY
action: create
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: name
value: DevOps Escalation
- name: description
value: Escalation Policy for devops
- name: num_loops
value: '1'
resource:
id: PD_ESCALATION_ID
summary: DevOps Escalation
type: escalation_policy_reference
self: https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID
html_url: https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID
execution_context:
request_id: 0cc413fb-8e7d-4414-b4bc-b7578bf3ba77
execution_time: '2021-01-05T16:33:51.951Z'
method:
type: browser
root_resource:
id: PD_ESCALATION_ID
summary: DevOps Escalation
type: escalation_policy_reference
self: https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID
html_url: https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID
limit: 10
next_cursor:
AuditRecordScheduleResponse:
summary: Response Example
value:
records:
- id: PD_ASSIGN_TEAM_TO_SCHEDULE
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
references:
- added:
- id: PD_TEAM123
summary: Devops
type: team_reference
self: https://api.pagerduty.com/teams/PD_TEAM123
html_url: https://mydomain.pagerduty.com/teams/PD_TEAM123
name: teams
resource:
id: PD_SCHEDULE_ID
summary: DevOps Schedule
type: schedule_reference
self: https://api.pagerduty.com/schedules/PD_SCHEDULE_ID
html_url: https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID
execution_context:
request_id: 13a1c0c3-545c-4ebb-4115-662fff9d8ad
execution_time: '2021-01-05T16:25:41.324Z'
method:
type: browser
root_resource:
id: PD_SCHEDULE_ID
summary: DevOps Schedule
type: schedule_reference
self: https://api.pagerduty.com/schedules/PD_SCHEDULE_ID
html_url: https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID
- id: PD_CREATE_SCHEDULE
action: create
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: name
value: DevOps Schedule
- name: description
value: Our DevOps Team Schedule
- name: time_zone
value: America/New_York
resource:
id: PD_SCHEDULE_ID
summary: DevOps Schedule
type: schedule_reference
self: https://api.pagerduty.com/schedules/PD_SCHEDULE_ID
html_url: https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID
execution_context:
request_id: 13a1c0c3-545c-4ebb-4115-662fff9d8ad
execution_time: '2021-01-05T16:25:41.315Z'
method:
type: browser
root_resource:
id: PD_SCHEDULE_ID
summary: DevOps Schedule
type: schedule_reference
self: https://api.pagerduty.com/schedules/PD_SCHEDULE_ID
html_url: https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID
limit: 10
next_cursor:
AuditRecordServiceResponse:
summary: Response Example
value:
records:
- id: PDRECORDID1_SERVICE_CREATED
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 111lDEOIH-534-4ljhLHJjh111
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
method:
type: api_token
truncated_token: 3usr
root_resource:
id: PN2YA40
type: service_reference
summary: Documentation Hub
action: create
details:
resource:
id: PD_SERVICE_ID
type: service_reference
summary: Documentation Hub
fields:
- name: name
value: Documentation Hub
- name: description
value: Centralized documentation
- name: incident_severity
value: always_high
- name: alert_creation
value: create_alerts_and_incidents
- name: auto_resolve_timeout
value: ''
- name: acknowledgement_timeout
value: ''
- name: alert_grouping
value:
- name: alert_grouping_timeout
value: ''
references:
- name: escalation_policy
added:
- id: PD_SERVICE_ID
summary: Default
type: escalation_policy_reference
next_cursor:
limit: 10
AuditRecordTeamResponse:
summary: Response Example
value:
records:
- id: PDRECORD_USER_ROLE_ON_TEAM
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 111lDEOIH-534-4ljhLHJjh111
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
method:
type: browser
root_resource:
id: PD_TEAM123
type: team_reference
summary: my DevOps team
self: https://api.pagerduty.com/teams/PD_TEAM123
html_url: https://mydomain.pagerduty.com/teams/PD_TEAM123
action: update
details:
resource:
id: PD_ADMIN_USER123
type: user_reference
summary: AA Admin User
self: https://api.pagerduty.com/users/PD_ADMIN_USER123
html_url: https://mydomain.pagerduty.com/users/PD_ADMIN_USER123
fields:
- name: members.role
value: manager
- id: PDRECORD_USER_ADDED_TO_TEAM
execution_time: '2020-06-04T15:30:16.272Z'
execution_context:
request_id: 111lDEOIH-534-4ljhLHJjh111
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
method:
type: browser
root_resource:
id: PD_TEAM123
type: team_reference
summary: DevOps
action: update
details:
resource:
id: PD_TEAM123
type: team_reference
summary: DevOps
references:
- name: members
added:
- id: PD_ADMIN_USER123
type: user_reference
summary: AA Admin User
self: https://api.pagerduty.com/users/PD_ADMIN_USER123
html_url: https://mydomain.pagerduty.com/users/PD_ADMIN_USER123
- id: PDRECORD_TEAM_CREATED
execution_time: '2020-06-04T15:25:04.113Z'
execution_context:
request_id: 222lDEOIH-534-4ljhLHJjh222
remote_address: 201.19.20.19
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
method:
type: browser
root_resource:
id: PD_TEAM123
type: team_reference
summary: DevOps
self: https://api.pagerduty.com/teams/PD_TEAM123
html_url: https://mydomain.pagerduty.com/teams/PD_TEAM123
action: create
details:
resource:
id: PD_TEAM123
type: team_reference
summary: DevOps
self: https://api.pagerduty.com/teams/PD_TEAM123
html_url: https://mydomain.pagerduty.com/teams/PD_TEAM123
fields:
- name: name
value: DevOps
- name: description
value: MyDevOps Team
- name: default_role
value: manager
next_cursor:
limit: 10
AuditRecordUserResponse:
summary: Response Example
value:
records:
- id: PD_ADD_HIGH_URGENCY_NOTIFICATION
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
references:
- added:
- id: PD_NOTIFICATION_RULE_HIGH
summary: 'High Urgency (Email: Default)'
type: assignment_notification_rule_reference
name: notification_rules
resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.343Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_ADD_HIGH_URGENCY_EMAIL_CONTACT
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: start_delay_in_minutes
value: '0'
- name: urgency
value: high
references:
- added:
- id: PD_CONTACT_METHOD
summary: Default
type: email_contact_method_reference
name: contact_method
resource:
id: PD_NOTIFICATION_RULE_HIGH
summary: 'High Urgency (Email: Default)'
type: assignment_notification_rule_reference
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.343Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_ADD_LOW_URGENCY_EMAIL_RULE
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: start_delay_in_minutes
value: '0'
- name: urgency
value: low
references:
- added:
- id: PD_CONTACT_METHOD
summary: Default
type: email_contact_method_reference
name: contact_method
resource:
id: PD_NOTIFICATION_RULE_LOW
summary: 'Low Urgency (Email: Default)'
type: assignment_notification_rule_reference
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.335Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_ADD_LOW_URGENCY_EMAIL_CONTACT
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
references:
- added:
- id: PD_NOTIFICATION_RULE_LOW
summary: 'Low Urgency (Email: Default)'
type: assignment_notification_rule_reference
name: notification_rules
resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.335Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_EMAIL_CONTACT_FOR_USER
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: label
value: Default
- name: type
value: email_contact_method
- name: address
value: [email protected]
resource:
id: PD_CONTACT_METHOD
summary: Default
type: email_contact_method_reference
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.327Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_ADD_EMAIL_CONTACT_TO_USER
action: update
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
references:
- added:
- id: PD_CONTACT_METHOD
summary: Default
type: email_contact_method_reference
name: contact_methods
resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution_time: '2021-01-05T15:17:32.327Z'
method:
type: browser
root_resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
- id: PD_CREATE_USER
action: create
actors:
- id: PDUSER
summary: John Snow
type: user_reference
self: https://api.pagerduty.com/users/PD_USER123
html_url: https://mydomain.pagerduty.com/users/PD_USER123
details:
fields:
- name: name
value: Test User
- name: role
value: user
- name: email
value: [email protected]
- name: time_zone
value: America/New_York
- name: description
value:
- name: job_title
value:
- name: color
value: brown
resource:
id: PD_USER_999
summary: Test User
type: user_reference
self: https://api.pagerduty.com/users/PD_USER_999
html_url: https://mydomain.pagerduty.com/users/PD_USER_999
execution_context:
request_id: a68929b2-d0f4-4def-b1d2-6bb744c44e3d
execution
# --- truncated at 32 KB (1476 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pagerduty/refs/heads/main/openapi/pagerduty-openapi-original.yml