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.
Operations
GET /escalation_policies
List escalation policies
List all of the existing escalation policies.
Escalation policies define which user should be alerted at which time.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#escalation-policies)
Scoped OAuth requires: `escalation_policies.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Escalation Policies"
],
"x-pd-requires-scope": "escalation_policies.read",
"operationId": "listEscalationPolicies",
"description": "List all of the existing escalation policies.\n\nEscalation policies define which user should be alerted at which time.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#escalation-policies)\n\nScoped OAuth requires: `escalation_policies.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List escalation policies",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "query",
"in": "query",
"description": "Filters the result, showing only the records whose name matches the query.",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
{
"name": "user_ids[]",
"in": "query",
"description": "Filters the results, showing only escalation policies on which any of the users is a target.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "team_ids[]",
"in": "query",
"description": "An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
}
],
"responses": {
"200": {
"description": "A paginated array of escalation policy objects.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"escalation_policies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EscalationPolicy"
}
}
},
"required": [
"escalation_policies"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"escalation_policies": [
{
"id": "PANZZEQ",
"type": "escalation_policy",
"summary": "Engineering Escalation Policy",
"on_call_handoff_notifications": "if_has_services",
"self": "https://api.pagerduty.com/escalation_policies/PANZZEQ",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PANZZEQ",
"name": "Engineering Escalation Policy",
"escalation_rules": [
{
"id": "PANZZEQ",
"escalation_delay_in_minutes": 30,
"targets": [
{
"id": "PEYSGVF",
"summary": "PagerDuty Admin",
"type": "user_reference",
"self": "https://api.pagerduty.com/users/PEYSGVF",
"html_url": "https://subdomain.pagerduty.com/users/PEYSGVF"
},
{
"id": "PI7DH85",
"summary": "Daily Engineering Rotation",
"type": "schedule_reference",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85"
}
]
}
],
"services": [
{
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
}
],
"num_loops": 0,
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
]
}
],
"limit": 25,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /escalation_policies/{id}
Get an escalation policy
Get information about an existing escalation policy and its rules.
Escalation policies define which user should be alerted at which time.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#escalation-policies)
Scoped OAuth requires: `escalation_policies.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Escalation Policies"
],
"x-pd-requires-scope": "escalation_policies.read",
"operationId": "getEscalationPolicy",
"description": "Get information about an existing escalation policy and its rules.\n\nEscalation policies define which user should be alerted at which time.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#escalation-policies)\n\nScoped OAuth requires: `escalation_policies.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Get an escalation policy",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"responses": {
"200": {
"description": "The escalation policy object.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"escalation_policy": {
"$ref": "#/components/schemas/EscalationPolicy"
}
},
"required": [
"escalation_policy"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy",
"summary": "Another Escalation Policy",
"on_call_handoff_notifications": "if_has_services",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA",
"name": "Another Escalation Policy",
"escalation_rules": [
{
"id": "PGHDV41",
"escalation_delay_in_minutes": 30,
"targets": [
{
"id": "PAM4FGS",
"summary": "Kyler Kuhn",
"type": "user_reference",
"self": "https://api.pagerduty.com/users/PAM4FGS",
"html_url": "https://subdomain.pagerduty.com/users/PAM4FGS"
},
{
"id": "PI7DH85",
"summary": "Daily Engineering Rotation",
"type": "schedule_reference",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85"
}
]
}
],
"services": [
{
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
}
],
"num_loops": 2,
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"description": "This is yet another escalation policy"
}
}
}
}
}
}
},
"400": {
"description": "Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/responses/Conflict/content/application~1json/schema"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /incidents
List incidents
List existing incidents.
An incident represents a problem or an issue that needs to be addressed and resolved.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.read",
"tags": [
"Incidents"
],
"operationId": "listIncidents",
"description": "List existing incidents.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List incidents",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page. Maximum of 100.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "date_range",
"in": "query",
"description": "When set to all, the since and until parameters and defaults are ignored.",
"schema": {
"type": "string",
"enum": [
"all"
]
}
},
{
"name": "incident_key",
"in": "query",
"description": "Incident de-duplication key. Incidents with child alerts do not have an incident key; querying by incident key will return incidents whose alerts have alert_key matching the given incident key.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
{
"name": "service_ids[]",
"in": "query",
"description": "Returns only the incidents associated with the passed service(s). This expects one or more service IDs.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "team_ids[]",
"in": "query",
"description": "An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "user_ids[]",
"in": "query",
"description": "Returns only the incidents currently assigned to the passed user(s). This expects one or more user IDs. Note: When using the assigned_to_user filter, you will only receive incidents with statuses of triggered or acknowledged. This is because resolved incidents are not assigned to any user.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "urgencies[]",
"in": "query",
"description": "Array of the urgencies of the incidents to be returned. Defaults to all urgencies. Account must have the `urgencies` ability to do this.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"high",
"low"
]
}
},
"style": "form"
},
{
"name": "statuses[]",
"in": "query",
"description": "Return only incidents with the given statuses. To query multiple statuses, pass `statuses[]` more than once, for example: `https://api.pagerduty.com/incidents?statuses[]=triggered&statuses[]=acknowledged`. (More status codes may be introduced in the future.)",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"triggered",
"acknowledged",
"resolved"
]
}
},
"style": "form"
},
{
"name": "sort_by",
"in": "query",
"description": "Used to specify both the field you wish to sort the results on (incident_number/created_at/resolved_at/urgency), as well as the direction (asc/desc) of the results. The sort_by field and direction should be separated by a colon. A maximum of two fields can be included, separated by a comma. Sort direction defaults to ascending. The account must have the `urgencies` ability to sort by the urgency.",
"style": "form",
"explode": false,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 2,
"uniqueItems": true,
"items": {
"type": "string",
"enum": [
"incident_number",
"incident_number:asc",
"incident_number:desc",
"created_at",
"created_at:asc",
"created_at:desc",
"resolved_at",
"resolved_at:asc",
"resolved_at:desc",
"urgency",
"urgency:asc",
"urgency:desc"
]
}
}
},
{
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
},
"in": "query",
"name": "since",
"description": "The start of the date range over which you want to search. Maximum range is 6 months and default is 1 month."
},
{
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
},
"in": "query",
"name": "until",
"description": "The end of the date range over which you want to search. Maximum range is 6 months and default is 1 month."
}
],
"responses": {
"200": {
"description": "A paginated array of incidents.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"incidents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Incident"
}
}
},
"required": [
"incidents"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"incidents": [
{
"id": "PT4KHLK",
"type": "incident",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK",
"incident_number": 1234,
"title": "The server is on fire.",
"created_at": "2015-10-06T21:30:42Z",
"updated_at": "2015-10-06T21:40:23Z",
"status": "resolved",
"incident_key": "baf7cf21b1da41b4b0221008339ff357",
"service": {
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
},
"assignments": [],
"assigned_via": "escalation_policy",
"last_status_change_at": "2015-10-06T21:38:23Z",
"resolved_at": "2015-10-06T21:38:23Z",
"first_trigger_log_entry": {
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry_reference",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV"
},
"alert_counts": {
"all": 2,
"triggered": 0,
"resolved": 2
},
"is_mergeable": true,
"incident_type": {
"name": "incident_default"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"pending_actions": [],
"acknowledgements": [],
"alert_grouping": {
"grouping_type": "advanced",
"started_at": "2015-10-06T21:30:42Z",
"ended_at": null,
"alert_grouping_active": true
},
"last_status_change_by": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"priority": {
"id": "P53ZZH5",
"type": "priority_reference",
"summary": "P2",
"self": "https://api.pagerduty.com/priorities/P53ZZH5"
},
"resolve_reason": null,
"conference_bridge": {
"conference_number": "+1-415-555-1212,,,,1234#",
"conference_url": "https://example.com/acb-123"
},
"incidents_responders": [],
"responder_requests": [],
"urgency": "high"
}
],
"limit": 1,
"offset": 0,
"more": true
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
PUT /incidents
Manage incidents
Acknowledge, resolve, escalate or reassign one or more incidents.
An incident represents a problem or an issue that needs to be addressed and resolved.
A maximum of 250 incidents may be updated at a time. If more than this number of incidents are given, the API will respond with status 413 (Request Entity Too Large).
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.write`
This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.write",
"x-pd-operation-limit": true,
"tags": [
"Incidents"
],
"operationId": "updateIncidents",
"description": "Acknowledge, resolve, escalate or reassign one or more incidents.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nA maximum of 250 incidents may be updated at a time. If more than this number of incidents are given, the API will respond with status 413 (Request Entity Too Large).\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.write`\n\nThis API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Manage incidents",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "From",
"in": "header",
"description": "The email address of a valid user associated with the account making the request.",
"required": true,
"schema": {
"type": "string",
"format": "email",
"minLength": 3,
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"incidents"
],
"properties": {
"incidents": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"incident",
"incident_reference"
]
},
"status": {
"type": "string",
"enum": [
"triggered",
"acknowledged",
"resolved"
]
},
"resolution": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"urgency": {
"type": "string",
"enum": [
"high",
"low"
]
},
"priority": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"priority_reference"
]
}
}
},
"assignments": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"assignee"
],
"properties": {
"assignee": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"user_reference"
]
}
}
}
}
}
},
"escalation_policy": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"escalation_policy_reference"
]
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "All of the updates succeeded.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"incidents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Incident"
}
}
},
"required": [
"incidents"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"incidents": [
{
"id": "PT4KHLK",
"type": "incident",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK",
"incident_number": 1234,
"created_at": "2015-10-06T21:30:42Z",
"updated_at": "2015-10-06T21:40:23Z",
"status": "resolved",
"title": "The server is on fire.",
"alert_counts": {
"all": 2,
"triggered": 0,
"resolved": 2
},
"pending_actions": [
{
"type": "unacknowledge",
"at": "2015-11-10T01:02:52Z"
},
{
"type": "resolve",
"at": "2015-11-10T04:31:52Z"
}
],
"incident_key": "baf7cf21b1da41b4b0221008339ff357",
"service": {
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
},
"assigned_via": "escalation_policy",
"assignments": [
{
"at": "2015-11-10T00:31:52Z",
"assignee": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"acknowledgements": [
{
"at": "2015-11-10T00:32:52Z",
"acknowledger": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"resolved_at": "2015-10-06T21:38:23Z",
"last_status_change_at": "2015-10-06T21:38:23Z",
"last_status_change_by": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"first_trigger_log_entry": {
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry_reference",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV"
},
"incident_type": {
"name": "major_incident"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"urgency": "high"
}
]
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"413": {
"$ref": "#/components/responses/RequestEntityTooLarge"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
POST /incidents
Create an Incident
Create an incident synchronously without a corresponding event from a monitoring service.
An incident represents a problem or an issue that needs to be addressed and resolved.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.write`
This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.write",
"x-pd-operation-limit": true,
"tags": [
"Incidents"
],
"operationId": "createIncident",
"description": "Create an incident synchronously without a corresponding event from a monitoring service.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.write`\n\nThis API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Create an Incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "From",
"in": "header",
"description": "The email address of a valid user associated with the account making the request.",
"required": true,
"schema": {
"type": "string",
"format": "email",
"minLength": 3,
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"incident"
],
"properties": {
"incident": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"service"
],
"properties": {
"type": {
"type": "string",
"enum": [
"incident"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"service": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"service_reference"
]
}
}
},
"priority": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"priority_reference"
]
}
}
},
"urgency": {
"type": "string",
"enum": [
"high",
"low"
]
},
"body": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"incident_body"
]
},
"details": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 8000
},
{
"type": "object"
}
]
}
}
},
"incident_key": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"assignments": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"assignee"
],
"properties": {
"assignee": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"user_reference"
]
}
}
}
}
}
},
"escalation_policy": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"escalation_policy_reference"
]
}
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "The incident object created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"incident": {
"$ref": "#/components/schemas/Incident"
}
},
"required": [
"incident"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"incident": {
"id": "PT4KHLK",
"type": "incident",
"title": "The server is on fire.",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK",
"incident_number": 1234,
"created_at": "2015-10-06T21:30:42Z",
"updated_at": "2015-10-06T21:40:23Z",
"status": "triggered",
"incident_key": "baf7cf21b1da41b4b0221008339ff357",
"service": {
"id": "PWIXJZS",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PWIXJZS",
"html_url": "https://subdomain.pagerduty.com/service-directory/PWIXJZS"
},
"priority": {
"id": "P53ZZH5",
"type": "priority_reference",
"summary": "P2",
"self": "https://api.pagerduty.com/priorities/P53ZZH5"
},
"assigned_via": "escalation_policy",
"assignments": [
{
"at": "2015-11-10T00:31:52Z",
"assignee": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"resolved_at": null,
"last_status_change_at": "2015-10-06T21:38:23Z",
"last_status_change_by": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"first_trigger_log_entry": {
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry_reference",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV"
},
"incident_type": {
"name": "major_incident"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"urgency": "high"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /incidents/{id}
Get an incident
Show detailed information about an incident. Accepts either an incident id, or an incident number.
An incident represents a problem or an issue that needs to be addressed and resolved.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.read",
"tags": [
"Incidents"
],
"operationId": "getIncident",
"description": "Show detailed information about an incident. Accepts either an incident id, or an incident number.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Get an incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"responses": {
"200": {
"description": "The incident requested.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"incident": {
"$ref": "#/components/schemas/Incident"
}
},
"required": [
"incident"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"incident": {
"id": "PT4KHLK",
"type": "incident",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK",
"incident_number": 1234,
"title": "The server is on fire.",
"created_at": "2015-10-06T21:30:42Z",
"updated_at": "2015-10-06T21:40:23Z",
"status": "acknowledged",
"incident_key": "baf7cf21b1da41b4b0221008339ff357",
"service": {
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
},
"assignments": [
{
"at": "2015-11-10T00:31:52Z",
"assignee": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"assigned_via": "escalation_policy",
"last_status_change_at": "2015-10-06T21:38:23Z",
"resolved_at": null,
"first_trigger_log_entry": {
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry_reference",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV"
},
"alert_counts": {
"all": 2,
"triggered": 1,
"resolved": 1
},
"is_mergeable": true,
"incident_type": {
"name": "incident_default"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"pending_actions": [
{
"type": "unacknowledge",
"at": "2015-11-10T01:02:52Z"
},
{
"type": "resolve",
"at": "2015-11-10T04:31:52Z"
}
],
"acknowledgements": [
{
"at": "2015-11-10T00:32:52Z",
"acknowledger": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"alert_grouping": {
"grouping_type": "advanced",
"started_at": "2015-10-06T21:30:42Z",
"ended_at": null,
"alert_grouping_active": true
},
"last_status_change_by": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"priority": {
"id": "P53ZZH5",
"type": "priority_reference",
"summary": "P2",
"self": "https://api.pagerduty.com/priorities/P53ZZH5"
},
"resolve_reason": null,
"conference_bridge": {
"conference_number": "+1-415-555-1212,,,,1234#",
"conference_url": "https://example.com/acb-123"
},
"incidents_responders": [
{
"state": "pending",
"user": {
"id": "PL7A2O4",
"type": "user_reference",
"summary": "Lee Turner",
"self": "https://api.pagerduty.com/users/PL7A2O4",
"html_url": "https://subdomain.pagerduty.com/users/PL7A2O4",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png"
},
"incident": {
"id": "PXP12GZ",
"type": "incident_reference",
"summary": "Ongoing Incident in Mailroom",
"self": "https://api.pagerduty.com/incidents/PXP12GZ",
"html_url": "https://subdomain.pagerduty.com/incidents/PXP12GZ"
},
"updated_at": "2018-08-09T14:40:48-07:00",
"message": "Please help with issue - join bridge at +1(234)-567-8910",
"requester": {
"id": "P09TT3C",
"type": "user_reference",
"summary": "Jane Doe",
"self": "https://api.pagerduty.com/users/P09TT3C",
"html_url": "https://subdomain.pagerduty.com/users/P09TT3C",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png"
},
"requested_at": "2018-08-09T21:40:49Z"
}
],
"responder_requests": [
{
"incident": {
"id": "PXP12GZ",
"type": "incident_reference",
"summary": "Ongoing Incident in Mailroom",
"self": "https://api.pagerduty.com/incidents/PXP12GZ",
"html_url": "https://subdomain.pagerduty.com/incidents/PXP12GZ"
},
"requester": {
"id": "P09TT3C",
"type": "user_reference",
"summary": "Jane Doe",
"self": "https://api.pagerduty.com/users/P09TT3C",
"html_url": "https://subdomain.pagerduty.com/users/P09TT3C"
},
"requested_at": "2018-08-16T14:55:17-07:00",
"message": "Please help with issue - join bridge at +1(234)-567-8910",
"responder_request_targets": [
{
"responder_request_target": {
"type": "user",
"id": "PL7A2O4",
"incidents_responders": [
{
"state": "pending",
"user": {
"id": "PL7A2O4",
"type": "user_reference",
"summary": "Lee Turner",
"self": "https://api.pagerduty.com/users/PL7A2O4",
"html_url": "https://subdomain.pagerduty.com/users/PL7A2O4",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png"
},
"incident": {
"id": "PXP12GZ",
"type": "incident_reference",
"summary": "Ongoing Incident in Mailroom",
"self": "https://api.pagerduty.com/incidents/PXP12GZ",
"html_url": "https://subdomain.pagerduty.com/incidents/PXP12GZ"
},
"updated_at": "2018-08-09T14:40:48-07:00",
"message": "Please help with issue - join bridge at +1(234)-567-8910",
"requester": {
"id": "P09TT3C",
"type": "user_reference",
"summary": "Jane Doe",
"self": "https://api.pagerduty.com/users/P09TT3C",
"html_url": "https://subdomain.pagerduty.com/users/P09TT3C",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png"
},
"requested_at": "2018-08-09T21:40:49Z"
}
]
}
}
]
}
],
"urgency": "high",
"custom_fields": [
{
"id": "PT4KHEE",
"type": "field_value",
"name": "environment",
"display_name": "Runtime Environment",
"description": "environment where incident occurred",
"data_type": "string",
"field_type": "single_value_fixed",
"value": "production"
}
]
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
PUT /incidents/{id}
Update an incident
Acknowledge, resolve, escalate or reassign an incident.
An incident represents a problem or an issue that needs to be addressed and resolved.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.write`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.write",
"tags": [
"Incidents"
],
"operationId": "updateIncident",
"description": "Acknowledge, resolve, escalate or reassign an incident.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.write`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Update an incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "From",
"in": "header",
"description": "The email address of a valid user associated with the account making the request.",
"required": true,
"schema": {
"type": "string",
"format": "email",
"minLength": 3,
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"incident"
],
"properties": {
"incident": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"incident",
"incident_reference"
]
},
"status": {
"type": "string",
"enum": [
"triggered",
"acknowledged",
"resolved"
]
},
"resolution": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"urgency": {
"type": "string",
"enum": [
"high",
"low"
]
},
"priority": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"priority_reference"
]
}
}
},
"assignments": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"assignee"
],
"properties": {
"assignee": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"user_reference"
]
}
}
}
}
}
},
"escalation_policy": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"escalation_policy_reference"
]
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The incident was updated.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"incident": {
"$ref": "#/components/schemas/Incident"
}
},
"required": [
"incident"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"incident": {
"id": "PT4KHLK",
"type": "incident",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK",
"incident_number": 1234,
"created_at": "2015-10-06T21:30:42Z",
"updated_at": "2015-10-06T21:40:23Z",
"status": "resolved",
"title": "The server is on fire.",
"pending_actions": [
{
"type": "unacknowledge",
"at": "2015-11-10T01:02:52Z"
},
{
"type": "resolve",
"at": "2015-11-10T04:31:52Z"
}
],
"incident_key": "baf7cf21b1da41b4b0221008339ff357",
"service": {
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
},
"priority": {
"id": "P53ZZH5",
"type": "priority_reference",
"summary": "P2",
"self": "https://api.pagerduty.com/priorities/P53ZZH5"
},
"assigned_via": "escalation_policy",
"assignments": [
{
"at": "2015-11-10T00:31:52Z",
"assignee": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"acknowledgements": [
{
"at": "2015-11-10T00:32:52Z",
"acknowledger": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"resolved_at": "2015-10-06T21:38:23Z",
"last_status_change_at": "2015-10-06T21:38:23Z",
"last_status_change_by": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"first_trigger_log_entry": {
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry_reference",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV"
},
"incident_type": {
"name": "major_incident"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"urgency": "high"
}
}
}
}
}
}
},
"400": {
"description": "Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/responses/Conflict/content/application~1json/schema"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /incidents/{id}/log_entries
List log entries for an incident
List log entries for the specified incident.
An incident represents a problem or an issue that needs to be addressed and resolved.
A Log Entry are a record of all events on your account.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.read",
"tags": [
"Incidents"
],
"operationId": "listIncidentLogEntries",
"description": "List log entries for the specified incident.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nA Log Entry are a record of all events on your account.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List log entries for an incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "since",
"in": "query",
"description": "The start of the date range over which you want to search.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "until",
"in": "query",
"description": "The end of the date range over which you want to search.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "is_overview",
"in": "query",
"description": "If `true`, will return a subset of log entries that show only the most important changes to the incident.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A paginated array of the incident's log entries.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"log_entries": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/AcknowledgeLogEntry"
},
{
"$ref": "#/components/schemas/AnnotateLogEntry"
},
{
"$ref": "#/components/schemas/AssignLogEntry"
},
{
"$ref": "#/components/schemas/DelegateLogEntry"
},
{
"$ref": "#/components/schemas/EscalateLogEntry"
},
{
"$ref": "#/components/schemas/ExhaustEscalationPathLogEntry"
},
{
"$ref": "#/components/schemas/NotifyLogEntry"
},
{
"$ref": "#/components/schemas/ReachAckLimitLogEntry"
},
{
"$ref": "#/components/schemas/ReachTriggerLimitLogEntry"
},
{
"$ref": "#/components/schemas/RepeatEscalationPathLogEntry"
},
{
"$ref": "#/components/schemas/ResolveLogEntry"
},
{
"$ref": "#/components/schemas/SnoozeLogEntry"
},
{
"$ref": "#/components/schemas/TriggerLogEntry"
},
{
"$ref": "#/components/schemas/UnacknowledgeLogEntry"
},
{
"$ref": "#/components/schemas/UrgencyChangeLogEntry"
},
{
"$ref": "#/components/schemas/FieldValueChangeLogEntry"
},
{
"$ref": "#/components/schemas/CustomFieldValueChangeLogEntry"
}
]
}
}
},
"required": [
"log_entries"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"log_entries": [
{
"id": "Q02JTSNZWHSEKV",
"type": "trigger_log_entry",
"summary": "Triggered through the API",
"self": "https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV",
"created_at": "2015-11-07T00:14:20Z",
"agent": {
"id": "PIJ90N7",
"type": "service_reference",
"summary": "My Mail Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7"
},
"channel": {
"type": "api"
},
"incident": {
"id": "PT4KHLK",
"type": "incident_reference",
"summary": "[#1234] The server is on fire.",
"self": "https://api.pagerduty.com/incidents/PT4KHLK",
"html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLK"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"contexts": [],
"event_details": {
"description": "Tasks::SFDCValidator - PD_Data__c - duplicates"
}
}
]
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /incidents/{id}/notes
List notes for an incident
List existing notes for the specified incident.
An incident represents a problem or an issue that needs to be addressed and resolved.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "incidents.read",
"tags": [
"Incidents"
],
"operationId": "listIncidentNotes",
"description": "List existing notes for the specified incident.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List notes for an incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"responses": {
"200": {
"description": "An array of notes.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"notes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IncidentNote"
}
}
},
"required": [
"notes"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"notes": [
{
"id": "PWL7QXS",
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"channel": {
"summary": "The PagerDuty website or APIs"
},
"content": "Firefighters are on the scene.",
"created_at": "2013-03-06T15:28:51-05:00",
"updated_at": "2023-10-01T12:00:00-05:00"
},
{
"id": "PCQC25",
"user": {
"id": "PXPGF42",
"type": "bot_user_reference",
"summary": "A Global Event Rule",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/event-rules/global/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b"
},
"channel": {
"id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
"type": "event_rule_reference",
"summary": "A Global Event Rule",
"self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
"html_url": "https://subdomain.pagerduty.com/event-rules/global/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b"
},
"content": "Initial alert information indicates a 1-alarm fire",
"created_at": "2013-03-06T15:28:42-05:00",
"updated_at": "2023-10-01T12:00:00-05:00"
}
]
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
POST /incidents/{id}/notes
Create a note on an incident
Create a new note for the specified incident.
An incident represents a problem or an issue that needs to be addressed and resolved.
A maximum of 2000 notes can be added to an incident.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)
Scoped OAuth requires: `incidents.write`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Incidents"
],
"x-pd-requires-scope": "incidents.write",
"operationId": "createIncidentNote",
"description": "Create a new note for the specified incident.\n\nAn incident represents a problem or an issue that needs to be addressed and resolved.\n\nA maximum of 2000 notes can be added to an incident.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#incidents)\n\nScoped OAuth requires: `incidents.write`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Create a note on an incident",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
{
"name": "From",
"in": "header",
"description": "The email address of a valid user associated with the account making the request.",
"required": true,
"schema": {
"type": "string",
"format": "email",
"minLength": 3,
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"note"
],
"properties": {
"note": {
"type": "object",
"additionalProperties": false,
"required": [
"content"
],
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The new note.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"note": {
"$ref": "#/components/schemas/IncidentNote"
}
},
"required": [
"note"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"note": {
"id": "PWL7QXS",
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
},
"channel": {
"summary": "The PagerDuty website or APIs"
},
"content": "Firefighters are on the scene.",
"created_at": "2013-03-06T15:28:51-05:00",
"updated_at": "2023-10-01T12:00:00-05:00"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /oncalls
List all of the on-calls
List the on-call entries during a given time range.
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.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#on-calls)
Scoped OAuth requires: `oncalls.read`
This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"On-Calls"
],
"x-pd-requires-scope": "oncalls.read",
"x-pd-operation-limit": true,
"operationId": "listOnCalls",
"description": "List the on-call entries during a given time range.\n\nAn on-call represents a contiguous unit of time for which a User will be on call for a given Escalation Policy and Escalation Rules.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#on-calls)\n\nScoped OAuth requires: `oncalls.read`\n\nThis API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List all of the on-calls",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "user_ids[]",
"in": "query",
"description": "Filters the results, showing only on-calls for the specified user IDs.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "escalation_policy_ids[]",
"in": "query",
"description": "Filters the results, showing only on-calls for the specified escalation policy IDs.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "schedule_ids[]",
"in": "query",
"description": "Filters the results, showing only on-calls for the specified schedule IDs. If `null` is provided in the array, it includes permanent on-calls due to direct user escalation targets.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "since",
"in": "query",
"description": "The start of the time range over which you want to search. If an on-call period overlaps with the range, it will be included in the result. Defaults to current time. On-call shifts are limited to 90 days in the future.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "until",
"in": "query",
"description": "The end of the time range over which you want to search. If an on-call period overlaps with the range, it will be included in the result. Defaults to current time. On-call shifts are limited to 90 days in the future, and the `until` time cannot be before the `since` time.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "earliest",
"in": "query",
"description": "This will filter on-calls such that only the earliest on-call for each combination of escalation policy, escalation level, and user is returned. This is useful for determining when the \"next\" on-calls are for a given set of filters.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A paginated array of on-call objects.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"oncalls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Oncall"
}
}
},
"required": [
"oncalls"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"oncalls": [
{
"user": {
"id": "PT23IWX",
"type": "user_reference",
"summary": "Tim Wright",
"self": "https://api.pagerduty.com/users/PT23IWX",
"html_url": "https://subdomain.pagerduty.com/users/PT23IWX"
},
"schedule": {
"id": "PI7DH85",
"type": "schedule_reference",
"summary": "Daily Engineering Rotation",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85"
},
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Engineering Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"escalation_level": 2,
"start": "2015-03-06T15:28:51-05:00",
"end": "2015-03-07T15:28:51-05:00"
}
],
"limit": 25,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /priorities
List priorities
List existing priorities, in order (most to least severe).
A priority is a label representing the importance and impact of an incident.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#priorities)
Scoped OAuth requires: `priorities.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Priorities"
],
"x-pd-requires-scope": "priorities.read",
"operationId": "listPriorities",
"description": "List existing priorities, in order (most to least severe).\n\nA priority is a label representing the importance and impact of an incident.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#priorities)\n\nScoped OAuth requires: `priorities.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List priorities",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A paginated array of priorities.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"priorities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Priority"
}
}
},
"required": [
"priorities"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"priorities": [
{
"id": "PSLWBL8",
"type": "priority",
"summary": "P1",
"self": "https://api.pagerduty.com/priorities/PSLWBL8",
"name": "P1",
"description": "Critical issue that warrants public notification and liaison with executive teams"
},
{
"id": "P53ZZH5",
"type": "priority",
"summary": "P2",
"self": "https://api.pagerduty.com/priorities/P53ZZH5",
"name": "P2",
"description": "Critical system issue actively impacting many customers' ability to use the product"
},
{
"id": "PGE9YCZ",
"type": "priority",
"summary": "P3",
"self": "https://api.pagerduty.com/priorities/PGE9YCZ",
"name": "P3",
"description": "Stability or minor customer-impacting issues that require immediate attention from service owners"
},
{
"id": "PVJPWYW",
"type": "priority",
"summary": "P4",
"self": "https://api.pagerduty.com/priorities/PVJPWYW",
"name": "P4",
"description": "Minor issues requiring action, but not affecting customer ability to use the product"
},
{
"id": "P81SUUT",
"type": "priority",
"summary": "P5",
"self": "https://api.pagerduty.com/priorities/P81SUUT",
"name": "P5",
"description": "Cosmetic issues or bugs, not affecting customer ability to use the product"
}
],
"limit": 25,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /schedules
List schedules
List the on-call schedules.
A Schedule determines the time periods that users are On-Call.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#schedules)
Scoped OAuth requires: `schedules.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Schedules"
],
"x-pd-requires-scope": "schedules.read",
"operationId": "listSchedules",
"description": "List the on-call schedules.\n\nA Schedule determines the time periods that users are On-Call.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#schedules)\n\nScoped OAuth requires: `schedules.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List schedules",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "query",
"in": "query",
"description": "Filters the result, showing only the records whose name matches the query.",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
{
"name": "since",
"in": "query",
"description": "The start of the date range over which you want to show schedule entries. Defaults to 2 weeks before until if an until is given. Optional parameter. When provided with include[] for schedule types, populates the rendered_schedule_entries fields in the response.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "until",
"in": "query",
"description": "The end of the date range over which you want to show schedule entries. Defaults to 2 weeks after since if a since is given. Optional parameter. When provided with include[] for schedule types, populates the rendered_schedule_entries fields in the response.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "team_ids[]",
"in": "query",
"description": "An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
}
],
"responses": {
"200": {
"description": "A paginated array of schedule objects.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"schedules": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Schedule"
}
}
},
"required": [
"schedules"
]
}
]
},
"examples": {
"Basic Example": {
"value": {
"schedules": [
{
"id": "PI7DH85",
"type": "schedule",
"summary": "Daily Engineering Rotation",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85",
"name": "Daily Engineering Rotation",
"time_zone": "America/New_York",
"description": "Rotation schedule for engineering",
"escalation_policies": [
{
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
}
],
"users": [
{
"id": "PEYSGVF",
"type": "user_reference",
"summary": "PagerDuty Admin",
"self": "https://api.pagerduty.com/users/PEYSGVF",
"html_url": "https://subdomain.pagerduty.com/users/PEYSGVF"
}
]
}
],
"limit": 100,
"offset": 0,
"more": false,
"total": null
}
},
"With Schedule Layers": {
"summary": "With Schedule Layers Included",
"value": {
"schedules": [
{
"id": "PI7DH85",
"type": "schedule",
"summary": "Daily Engineering Rotation",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85",
"name": "Daily Engineering Rotation",
"time_zone": "America/New_York",
"description": "Rotation schedule for engineering",
"escalation_policies": [
{
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
}
],
"users": [
{
"id": "PEYSGVF",
"type": "user_reference",
"summary": "PagerDuty Admin",
"self": "https://api.pagerduty.com/users/PEYSGVF",
"html_url": "https://subdomain.pagerduty.com/users/PEYSGVF"
}
],
"schedule_layers": [
{
"name": "Night Shift",
"start": "2015-11-06T20:00:00-05:00",
"end": "2016-11-06T20:00:00-05:00",
"rotation_virtual_start": "2015-11-06T20:00:00-05:00",
"rotation_turn_length_seconds": 86400,
"users": [
{
"user": {
"id": "PEYSGVF",
"type": "user_reference",
"summary": "PagerDuty Admin",
"self": "https://api.pagerduty.com/users/PEYSGVF",
"html_url": "https://subdomain.pagerduty.com/users/PEYSGVF"
}
}
],
"restrictions": [
{
"type": "daily_restriction",
"start_time_of_day": "08:00:00",
"duration_seconds": 32400
}
]
}
]
}
],
"limit": 100,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /schedules/{id}
Get a schedule
Show detailed information about a schedule, including entries for each layer.
Scoped OAuth requires: `schedules.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Schedules"
],
"x-pd-requires-scope": "schedules.read",
"operationId": "getSchedule",
"description": "Show detailed information about a schedule, including entries for each layer.\nScoped OAuth requires: `schedules.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Get a schedule",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "since",
"in": "query",
"description": "The start of the date range over which you want to show schedule entries. Defaults to 2 weeks before until if an until is given. Optional parameter. When provided with include[] for schedule types, populates the rendered_schedule_entries fields in the response.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "until",
"in": "query",
"description": "The end of the date range over which you want to show schedule entries. Defaults to 2 weeks after since if a since is given. Optional parameter. When provided with include[] for schedule types, populates the rendered_schedule_entries fields in the response.",
"schema": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
}
},
{
"name": "overflow",
"in": "query",
"description": "Any on-call schedule entries that pass the date range bounds will be truncated at the bounds, unless the parameter `overflow=true` is passed. This parameter defaults to false.\nFor instance, if your schedule is a rotation that changes daily at midnight UTC, and your date range is from `2011-06-01T10:00:00Z` to `2011-06-01T14:00:00Z`:\n\n\n- If you don't pass the `overflow=true` parameter, you will get one schedule entry returned with a start of `2011-06-01T10:00:00Z` and end of `2011-06-01T14:00:00Z`.\n- If you do pass the `overflow=true` parameter, you will get one schedule entry returned with a start of `2011-06-01T00:00:00Z` and end of `2011-06-02T00:00:00Z`.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "id",
"description": "The ID of the schedule.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"example": "P2LJD7G"
}
],
"responses": {
"200": {
"description": "The schedule object.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedule": {
"$ref": "#/components/schemas/Schedule"
}
},
"required": [
"schedule"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"schedule": {
"id": "PI7DH85",
"type": "schedule",
"summary": "Daily Engineering Rotation",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85",
"name": "Daily Engineering Rotation",
"time_zone": "America/New_York",
"description": "Rotation schedule for engineering",
"escalation_policies": [
{
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
}
],
"users": [
{
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
],
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"schedule_layers": [
{
"name": "Layer 1",
"rendered_schedule_entries": [
{
"start": "2015-11-09T08:00:00-05:00",
"end": "2015-11-09T17:00:00-05:00",
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"rendered_coverage_percentage": 37.5,
"id": "PG68P1M",
"start": "2015-11-06T21:00:00-05:00",
"rotation_virtual_start": "2015-11-06T20:00:00-05:00",
"rotation_turn_length_seconds": 86400,
"users": [
{
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"restrictions": [
{
"type": "daily_restriction",
"start_time_of_day": "08:00:00",
"duration_seconds": 32400
}
]
}
],
"overrides_subschedule": {
"name": "Overrides",
"rendered_schedule_entries": [],
"rendered_coverage_percentage": 0
},
"final_schedule": {
"name": "Final Schedule",
"rendered_schedule_entries": [
{
"start": "2015-11-10T08:00:00-05:00",
"end": "2015-11-10T17:00:00-05:00",
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"rendered_coverage_percentage": 37.5
},
"next_oncall_for_user": {
"start": "2021-12-27T16:00:00-05:00",
"end": "2022-01-03T16:00:00-05:00",
"user": [
{
"id": "PCQNVHM",
"type": "user_reference",
"summary": "Jim Halpert",
"self": "https://api.pagerduty.com/users/PCQNVHM",
"html_url": "https://subdomain.pagerduty.com/users/PCQNVHM"
}
]
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
PUT /schedules/{id}
Update a schedule
Update an existing on-call schedule.
A Schedule determines the time periods that users are On-Call.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#schedules)
Scoped OAuth requires: `schedules.write`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Schedules"
],
"x-pd-requires-scope": "schedules.write",
"operationId": "updateSchedule",
"description": "Update an existing on-call schedule.\n\nA Schedule determines the time periods that users are On-Call.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#schedules)\n\nScoped OAuth requires: `schedules.write`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Update a schedule",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"schedule"
],
"properties": {
"schedule": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"time_zone",
"schedule_layers"
],
"properties": {
"type": {
"type": "string",
"enum": [
"schedule"
]
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"time_zone": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"schedule_layers": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"start",
"users",
"rotation_virtual_start",
"rotation_turn_length_seconds"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"start": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
},
"end": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
},
"rotation_virtual_start": {
"type": "string",
"format": "date-time",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,6})?(Z|[+-]\\d{2}:\\d{2})$"
},
"rotation_turn_length_seconds": {
"type": "integer",
"minimum": 3600,
"maximum": 31536000
},
"users": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"user"
],
"properties": {
"user": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"type": {
"type": "string",
"enum": [
"user_reference"
]
}
}
}
}
}
},
"restrictions": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"duration_seconds",
"start_time_of_day"
],
"properties": {
"type": {
"type": "string",
"enum": [
"daily_restriction",
"weekly_restriction"
]
},
"duration_seconds": {
"type": "integer",
"minimum": 60,
"maximum": 604800
},
"start_time_of_day": {
"type": "string",
"format": "partial-time",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d$"
},
"start_day_of_week": {
"type": "integer",
"minimum": 1,
"maximum": 7
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The updated schedule.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedule": {
"$ref": "#/components/schemas/Schedule"
}
},
"required": [
"schedule"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"schedule": {
"id": "PI7DH85",
"type": "schedule",
"summary": "Daily Engineering Rotation",
"self": "https://api.pagerduty.com/schedules/PI7DH85",
"html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85",
"name": "Daily Engineering Rotation",
"time_zone": "America/New_York",
"description": "Rotation schedule for engineering",
"escalation_policies": [
{
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
}
],
"users": [
{
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
],
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"schedule_layers": [
{
"name": "Layer 1",
"rendered_schedule_entries": [],
"id": "PG68P1M",
"start": "2015-11-06T20:00:00-05:00",
"rotation_virtual_start": "2015-11-06T20:00:00-05:00",
"rotation_turn_length_seconds": 86400,
"users": [
{
"user": {
"id": "PXPGF42",
"type": "user_reference",
"summary": "Regina Phalange",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42"
}
}
],
"restrictions": [
{
"type": "daily_restriction",
"start_time_of_day": "08:00:00",
"duration_seconds": 32400
}
]
}
],
"overrides_subschedule": {
"name": "Overrides",
"rendered_schedule_entries": []
},
"final_schedule": {
"name": "Final Schedule",
"rendered_schedule_entries": []
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /services
List services
List existing Services.
A service may represent an application, component, or team you wish to open incidents against.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#services)
Scoped OAuth requires: `services.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Services"
],
"operationId": "listServices",
"x-pd-requires-scope": "services.read",
"description": "List existing Services.\n\nA service may represent an application, component, or team you wish to open incidents against.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#services)\n\nScoped OAuth requires: `services.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List services",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "query",
"in": "query",
"description": "Filters the result, showing only the records whose name matches the query.",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "team_ids[]",
"in": "query",
"description": "An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "name",
"in": "query",
"description": "Filters the results, showing only services with the specified name.",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "A paginated array of services.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"services": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Service"
}
}
},
"required": [
"services"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"services": [
{
"id": "PIJ90N7",
"summary": "My Application Service",
"type": "service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7",
"name": "My Application Service",
"auto_resolve_timeout": 14400,
"acknowledgement_timeout": 600,
"created_at": "2015-11-06T11:12:51-05:00",
"status": "active",
"alert_creation": "create_alerts_and_incidents",
"alert_grouping_parameters": {
"type": "intelligent"
},
"integrations": [
{
"id": "PQ12345",
"type": "generic_email_inbound_integration_reference",
"summary": "Email Integration",
"self": "https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345",
"html_url": "https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345"
}
],
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"incident_urgency_rule": {
"type": "use_support_hours",
"during_support_hours": {
"type": "constant",
"urgency": "high"
},
"outside_support_hours": {
"type": "constant",
"urgency": "low"
}
},
"support_hours": {
"type": "fixed_time_per_day",
"time_zone": "America/Lima",
"start_time": "09:00:00",
"end_time": "17:00:00",
"days_of_week": [
1,
2,
3,
4,
5
]
},
"scheduled_actions": [
{
"type": "urgency_change",
"at": {
"type": "named_time",
"name": "support_hours_start"
},
"to_urgency": "high"
}
],
"auto_pause_notifications_parameters": {
"enabled": true,
"timeout": 300
}
}
],
"limit": 25,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /services/{id}
Get a service
Get details about an existing service.
A service may represent an application, component, or team you wish to open incidents against.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#services)
Scoped OAuth requires: `services.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Services"
],
"operationId": "getService",
"x-pd-requires-scope": "services.read",
"description": "Get details about an existing service.\n\nA service may represent an application, component, or team you wish to open incidents against.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#services)\n\nScoped OAuth requires: `services.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Get a service",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"responses": {
"200": {
"description": "The service requested.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"service": {
"$ref": "#/components/schemas/Service"
}
},
"required": [
"service"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"service": {
"id": "PIJ90N7",
"type": "service",
"summary": "My Application Service",
"self": "https://api.pagerduty.com/services/PIJ90N7",
"html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7",
"name": "My Application Service",
"auto_resolve_timeout": 14400,
"acknowledgement_timeout": 600,
"created_at": "2015-11-06T11:12:51-05:00",
"status": "active",
"alert_creation": "create_alerts_and_incidents",
"integrations": [
{
"id": "PQ12345",
"type": "generic_email_inbound_integration_reference",
"summary": "Email Integration",
"self": "https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345",
"html_url": "https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345"
}
],
"escalation_policy": {
"id": "PT20YPA",
"type": "escalation_policy_reference",
"summary": "Another Escalation Policy",
"self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
"html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
},
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"incident_urgency_rule": {
"type": "use_support_hours",
"during_support_hours": {
"type": "constant",
"urgency": "high"
},
"outside_support_hours": {
"type": "constant",
"urgency": "low"
}
},
"support_hours": {
"type": "fixed_time_per_day",
"time_zone": "America/Lima",
"start_time": "09:00:00",
"end_time": "17:00:00",
"days_of_week": [
1,
2,
3,
4,
5
]
},
"scheduled_actions": [
{
"type": "urgency_change",
"at": {
"type": "named_time",
"name": "support_hours_start"
},
"to_urgency": "high"
}
],
"auto_pause_notifications_parameters": {
"enabled": true,
"timeout": 300
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /users
List users
List users of your PagerDuty account, optionally filtered by a search query.
Users are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)
Scoped OAuth requires: `users.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "users.read",
"tags": [
"Users"
],
"operationId": "listUsers",
"description": "List users of your PagerDuty account, optionally filtered by a search query.\n\nUsers are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)\n\nScoped OAuth requires: `users.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "List users",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "query",
"in": "query",
"description": "Filters the result, showing only the records whose name matches the query.",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
{
"name": "team_ids[]",
"in": "query",
"description": "An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.",
"explode": true,
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"style": "form"
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "The number of results per page.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "Offset to start pagination search results.",
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
{
"name": "total",
"in": "query",
"required": false,
"description": "By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.\n\nSee our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.\n",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"description": "A paginated array of users.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Pagination"
},
{
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
},
"required": [
"users"
]
}
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"users": [
{
"id": "PXPGF42",
"type": "user",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42",
"name": "Earline Greenholt",
"email": "125.greenholt.earline@graham.name",
"time_zone": "America/Lima",
"color": "green",
"role": "admin",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png",
"description": "I'm the boss",
"invitation_sent": false,
"created_via_sso": true,
"contact_methods": [
{
"id": "PTDVERC",
"type": "email_contact_method_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PTDVERC"
}
],
"notification_rules": [
{
"id": "P8GRWKK",
"type": "assignment_notification_rule_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/P8GRWKK",
"html_url": null
}
],
"job_title": "Director of Engineering",
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
]
},
{
"id": "PAM4FGS",
"type": "user",
"summary": "Kyler Kuhn",
"self": "https://api.pagerduty.com/users/PAM4FGS",
"html_url": "https://subdomain.pagerduty.com/users/PAM4FGS",
"name": "Kyler Kuhn",
"email": "126_dvm_kyler_kuhn@beahan.name",
"time_zone": "Asia/Hong_Kong",
"color": "red",
"role": "admin",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png",
"description": "Actually, I am the boss",
"invitation_sent": false,
"created_via_sso": false,
"contact_methods": [
{
"id": "PVMGSML",
"type": "email_contact_method_reference",
"summary": "Work",
"self": "https://api.pagerduty.com/users/PAM4FGS/contact_methods/PVMGSMLL"
}
],
"notification_rules": [
{
"id": "P8GRWKK",
"type": "assignment_notification_rule_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/P8GRWKK",
"html_url": null
}
],
"job_title": "Senior Engineer",
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
]
}
],
"limit": 25,
"offset": 0,
"more": false,
"total": null
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /users/{id}
Get a user
Get details about an existing user.
Users are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)
Scoped OAuth requires: `users.read`
PurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"x-pd-requires-scope": "users.read",
"tags": [
"Users"
],
"operationId": "getUser",
"description": "Get details about an existing user.\n\nUsers are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)\n\nScoped OAuth requires: `users.read`\n\nPurpleSuite executable core. Request bodies are closed to undeclared properties and bounded; `include[]`, `time_zone` and the unlisted sort orders are removed from this document rather than accepted and ignored. `self`/`html_url` are omitted from responses so no emitted link points at a vendor origin.",
"summary": "Get a user",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
},
{
"name": "id",
"description": "The ID of the resource.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
}
],
"responses": {
"200": {
"description": "The user requested.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
},
"required": [
"user"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"user": {
"id": "PXPGF42",
"type": "user",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42",
"name": "Earline Greenholt",
"email": "125.greenholt.earline@graham.name",
"time_zone": "America/Lima",
"color": "green",
"role": "admin",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png",
"description": "I'm the boss",
"invitation_sent": false,
"created_via_sso": true,
"contact_methods": [
{
"id": "PTDVERC",
"type": "email_contact_method_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PTDVERC"
}
],
"notification_rules": [
{
"id": "P8GRWKK",
"type": "assignment_notification_rule_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/P8GRWKK",
"html_url": null
}
],
"job_title": "Director of Engineering",
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
],
"http_cal_url": "https://webcal.pagerduty.com/private/ABCDEFGHIJKLMNOP/feed",
"web_cal_url": "webcal://webcal.pagerduty.com/private/ABCDEFGHIJKLMNOP/feed"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "modeled-core"
}
GET /users/me
Get the current user
Get details about the current user.
This endpoint can only be used with a [user-level API key](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or a key generated through an OAuth flow. This will not work if the request is made with an account-level access token.
Users are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.
For more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)
Not available in PurpleSuite: the instance key stands in for an account-scoped REST API key, which has no requester user. This operation validates the request and returns the vendor's error envelope; it never returns a synthetic user.
Authentication
[
{
"api_key": []
}
]
Request, responses and operation details
{
"tags": [
"Users"
],
"operationId": "getCurrentUser",
"description": "Get details about the current user.\n\nThis endpoint can only be used with a [user-level API key](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or a key generated through an OAuth flow. This will not work if the request is made with an account-level access token.\n\nUsers are members of a PagerDuty account that have the ability to interact with Incidents and other data on the account.\n\nFor more information see the [API Concepts Document](../../api-reference/a47605517c19a-api-concepts#users)\n\nNot available in PurpleSuite: the instance key stands in for an account-scoped REST API key, which has no requester user. This operation validates the request and returns the vendor's error envelope; it never returns a synthetic user.",
"summary": "Get the current user",
"parameters": [
{
"name": "Accept",
"description": "The `Accept` header is used as a versioning header.",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/vnd.pagerduty+json;version=2"
]
}
},
{
"name": "Content-Type",
"in": "header",
"required": false,
"schema": {
"type": "string",
"enum": [
"application/json"
]
}
}
],
"responses": {
"200": {
"description": "The requesting user.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
},
"required": [
"user"
]
},
"examples": {
"response": {
"summary": "Response Example",
"value": {
"user": {
"id": "PXPGF42",
"type": "user",
"summary": "Earline Greenholt",
"self": "https://api.pagerduty.com/users/PXPGF42",
"html_url": "https://subdomain.pagerduty.com/users/PXPGF42",
"name": "Earline Greenholt",
"email": "125.greenholt.earline@graham.name",
"time_zone": "America/Lima",
"color": "green",
"role": "admin",
"avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png",
"description": null,
"invitation_sent": false,
"job_title": "Director of Engineering",
"created_via_sso": "true,",
"contact_methods": [
{
"id": "PTDVERC",
"type": "email_contact_method_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PTDVERC",
"html_url": null
}
],
"notification_rules": [
{
"id": "P8GRWKK",
"type": "assignment_notification_rule_reference",
"summary": "Default",
"self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/PTDVERC",
"html_url": null
}
],
"teams": [
{
"id": "PQ9K7I8",
"type": "team_reference",
"summary": "Engineering",
"self": "https://api.pagerduty.com/teams/PQ9K7I8",
"html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
}
]
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/ArgumentError"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
},
"x-purplesuite-classification": "unavailable"
}