# PagerDuty API Reference > Full content of every PagerDuty API operation, one block per operation, each headed by its canonical URL. The index is at https://docs.pagerduty.com/llms.txt; the articles are at https://docs.pagerduty.com/llms-full.txt. --- URL: https://docs.pagerduty.com/developer/api/reference/events-v1/send-event/create-v1-event # Send an event to PagerDuty `POST https://events.pagerduty.com/generic/2010-04-15/create_event.json` Your monitoring tools should send PagerDuty a trigger event to report a new problem, or update an ongoing problem, depending on the event type. ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `service_key` | string | yes | The GUID of one of your "Generic API" services. This is the "Integration Key" listed on a Generic API's service detail page. | | `event_type` | string | yes | The type of event. Can be `trigger`, `acknowledge` or `resolve`. One of: `trigger`, `acknowledge`, `resolve`. | | `incident_key` | string | | Identifies the incident to `trigger`, `acknowledge`, or `resolve`. Required unless the `event_type` is `trigger`. | | `description` | string | | Text that will appear in the incident's log associated with this event. Required for `trigger` events. | | `details` | object | | An arbitrary JSON object containing any data you'd like included in the incident log. | | `client` | string | | The name of the monitoring client that is triggering this event. (This field is only used for `trigger` events.) | | `client_url` | string (url) | | The URL of the monitoring client that is triggering this event. (This field is only used for `trigger` events.) | | `contexts` | array of one of: object \| object | | Contexts to be included with the incident trigger such as links to graphs or images. (This field is only used for `trigger` events.) | | `contexts[].type` | string | yes | (option 1) The type of context being attached to the incident. One of: `link`. | | `contexts[].href` | string (url) | yes | (option 1) The link being attached to the incident. | | `contexts[].text` | string | | (option 1) Optional information pertaining to this context link. | | `contexts[].type` | string | yes | (option 2) The type of context being attached to the incident. One of: `image`. | | `contexts[].src` | string (url) | yes | (option 2) The source of the image being attached to the incident. This image must be served via HTTPS. | | `contexts[].href` | string (url) | | (option 2) Optional link for the image. | | `contexts[].alt` | string | | (option 2) Optional alternative text for the image. | Example: Example Request Body ```json { "service_key": "e93facc04764012d7bfb002500d5d1a6", "incident_key": "srv01/HTTP", "event_type": "trigger", "description": "FAILURE for production/HTTP on machine srv01.acme.com", "client": "Sample Monitoring Service", "client_url": "https://monitoring.service.com", "details": { "ping time": "1500ms", "load avg": 0.75 }, "contexts": [ { "type": "link", "href": "http://acme.pagerduty.com" }, { "type": "link", "href": "http://acme.pagerduty.com" }, { "text": "View the incident on PagerDuty", "type": "image", "src": "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1" }, { "type": "image", "src": "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1", "href": "https://google.com" } ] } ``` ## Response 200 The incident has been opened or updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | A short name for the error, or "success" if successful. | | `incident_key` | string | | The key of the incident that will be affected by the request, if successful. | | `message` | string | | A description of the problem, or "Event processed" if successful. | Example: Example Success Response ```json { "status": "success", "message": "Event processed", "incident_key": "srv01/HTTP" } ``` ## Response 400 Invalid event format (i.e. JSON parse error) or incorrect event structure ## Response 403 Rate limit reached (too many Events API requests) ## Response 5XX An error occurred on a request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | A short name for the error. | | `message` | string | yes | A description of the problem. | | `errors` | array of string | | An array of specific error messages. | Example: Example Error Response ```json { "status": "unrecognized object", "message": "Event object format is unrecognized", "errors": [ "JSON parse error" ] } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/events-v2/send-change-event/create-change-event # Send change events to the PagerDuty Events API `POST https://events.pagerduty.com/v2/change/enqueue` Change Events API enables you to send informational events about recent changes such as code deploys and system config changes from any system that can make an outbound HTTP connection. These events do not create incidents and do not send notifications; they are shown in context with incidents on the same PagerDuty service. ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `payload` | object | yes | Fields adding additional context about the location, impact, and character of the PagerDuty event. | | `payload.summary` | string | yes | A brief text summary of the event, used to generate the summaries/titles of any associated alerts. | | `payload.timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. | | `payload.source` | string | | The unique location of the affected system, preferably a hostname or FQDN. | | `payload.custom_details` | object | | Additional details about the event and affected system. | | `routing_key` | string | yes | The GUID of one of your Events API V2 integrations. This is the "Integration Key" listed on the Events API V2 integration's detail page. | | `links` | array of object | | Links to be shown on the alert and/or corresponding incident. | | `links[].href` | string (url) | yes | The link being attached to an incident or alert. | | `links[].text` | string | | Optional information pertaining to this context link. | | `images` | array of object | | Images to be displayed on the alert and/or corresponding incident. | | `images[].src` | string (url) | yes | The source of the image being attached to the incident or alert. This image must be served via HTTPS. | | `images[].href` | string (url) | | Optional link for the image. | | `images[].alt` | string | | Optional alternative text for the image. | Example: Build example Change Event Body ```json { "routing_key": "737ea619db564d41bd9824063e1f6b08", "payload": { "summary": "Build Success: Increase snapshot create timeout to 30 seconds", "timestamp": "2015-07-17T08:42:58.315+0000", "source": "prod-build-agent-i-0b148d1040d565540", "custom_details": { "build_state": "passed", "build_number": "220", "run_time": "1236s" } }, "links": [ { "href": "https://buildpipeline.com/pagerduty/deployment/builds/220", "text": "View in Build Pipeline" } ], "images": [ { "src": "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1", "href": "https://google.com", "alt": "An example link with an image" } ] } ``` Example: Commited example Change Event Body ```json { "routing_key": "737ea619db564d41bd9824063e1f8au1", "payload": { "summary": "Merge Pull Request", "timestamp": "2015-07-17T08:42:58.315+0000", "source": "git", "custom_details": { "author": "Pagerduty" } }, "links": [ { "href": "https://buildpipeline.com/pagerduty/deployment/builds/220", "text": "View in Build Pipeline" } ] } ``` ## Response 202 An alert has been created or updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | Returns "success" if successful, or a short error message in case of a failure. | | `dedup_key` | string | | The key used to correlate triggers, acknowledges, and resolves for the same alert. | | `message` | string | | A description of the problem, or "Event processed" if successful. | Example: Example Success Response ```json { "status": "success", "message": "Event processed", "dedup_key": "srv01/HTTP" } ``` ## Response 400 #/components/responses/ArgumentError ## Response 429 #/components/responses/TooManyRequests ## Response 5XX An error occurred on a request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | A short name for the error. | | `message` | string | yes | A description of the problem. | | `errors` | array of string | | An array of specific error messages. | Example: Example Error Response ```json { "status": "Unrecognized object", "message": "Event object format is unrecognized", "errors": [ "JSON parse error" ] } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/events-v2/send-event/create-v2-event # Send an event to PagerDuty `POST https://events.pagerduty.com/v2/enqueue` Your monitoring tools should send PagerDuty a trigger event to report a new problem, or update an ongoing problem, depending on the event type. ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `payload` | object | | Fields adding additional context about the location, impact, and character of the PagerDuty event. | | `payload.summary` | string | yes | A brief text summary of the event, used to generate the summaries/titles of any associated alerts. | | `payload.timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. | | `payload.severity` | | yes | The perceived severity of the status the event is describing withrespect to the affected system. One of: `critical`, `warning`, `error`, `info`. | | `payload.source` | string | yes | The unique location of the affected system, preferably a hostname or FQDN. | | `payload.component` | string | | Component of the source machine that is responsible for the event. | | `payload.group` | string | | Logical grouping of components of a service. | | `payload.class` | string | | The class/type of the event. | | `payload.custom_details` | object | | Additional details about the event and affected system. | | `routing_key` | string | yes | The GUID of one of your Events API V2 integrations. This is the "Integration Key" listed on the Events API V2 integration's detail page. | | `event_action` | | yes | The type of event. Can be `trigger`, `acknowledge` or `resolve`. One of: `trigger`, `acknowledge`, `resolve`. | | `dedup_key` | string | | Identifies the alert to `trigger`, `acknowledge`, or `resolve`. Required unless the `event_type` is `trigger`. | | `client` | string | | The name of the monitoring client that is triggering this event. (This field is only used for `trigger` events.) | | `client_url` | string (url) | | The URL of the monitoring client that is triggering this event. (This field is only used for `trigger` events.) | | `links` | array of object | | Links to be shown on the alert and/or corresponding incident. | | `links[].href` | string (url) | yes | The link being attached to an incident or alert. | | `links[].text` | string | | Optional information pertaining to this context link. | | `images` | array of object | | Images to be displayed on the alert and/or corresponding incident. | | `images[].src` | string (url) | yes | The source of the image being attached to the incident or alert. This image must be served via HTTPS. | | `images[].href` | string (url) | | Optional link for the image. | | `images[].alt` | string | | Optional alternative text for the image. | Example: Example Event Body ```json { "payload": { "summary": "DISK at 99% on machine prod-datapipe03.example.com", "timestamp": "2015-07-17T08:42:58.315+0000", "severity": "critical", "source": "prod-datapipe03.example.com", "component": "mysql", "group": "prod-datapipe", "class": "disk", "custom_details": { "free space": "1%", "ping time": "1500ms", "load avg": 0.75 } }, "routing_key": "e93facc04764012d7bfb002500d5d1a6", "dedup_key": "srv01/mysql", "event_action": "trigger", "client": "Sample Monitoring Service", "client_url": "https://monitoring.service.com", "links": [ { "href": "http://pagerduty.example.com", "text": "An example link." } ], "images": [ { "src": "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1", "href": "https://google.com", "alt": "An example link with an image" } ] } ``` ## Response 202 An alert has been created or updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | Returns "success" if successful, or a short error message in case of a failure. | | `dedup_key` | string | | The key used to correlate triggers, acknowledges, and resolves for the same alert. | | `message` | string | | A description of the problem, or "Event processed" if successful. | Example: Example Success Response ```json { "status": "success", "message": "Event processed", "dedup_key": "srv01/HTTP" } ``` ## Response 400 #/components/responses/ArgumentError ## Response 429 #/components/responses/TooManyRequests ## Response 5XX An error occurred on a request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | yes | A short name for the error. | | `message` | string | yes | A description of the problem. | | `errors` | array of string | | An array of specific error messages. | Example: Example Error Response ```json { "status": "Unrecognized object", "message": "Event object format is unrecognized", "errors": [ "JSON parse error" ] } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/account-mappings/get-account-mapping # Get an account mapping `GET https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}` Get detailed information about a specific account mapping. An Account Mapping establishes a connection between a PagerDuty account and a Jira Cloud instance, enabling integration and synchronization between the two platforms. Scoped OAuth requires: `jira_cloud_accounts.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Response 200 The account mapping requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `created_at` | string | yes | The time when the account mapping was created. | | `id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `jira_cloud_account` | object | yes | Details of the Jira Cloud instance connected to the PagerDuty account. | | `jira_cloud_account.base_url` | string | yes | The base URL of the Jira Cloud instance, used for API calls and constructing links. | | `pagerduty_account` | object | yes | Details of the PagerDuty account to which the integration is connected. | | `pagerduty_account.subdomain` | string | yes | The unique subdomain of the PagerDuty account, used to identify and access the account (e.g., `acme` in `https://acme.pagerduty.com`). | | `updated_at` | string \| null | | The time when the account mapping was last modified. | Example: Response Example ```json { "created_at": "2024-09-12T12:34:55.000Z", "id": "PIJ90N7", "jira_cloud_account": { "base_url": "https://atlassian-subdomain.atlassian.net" }, "pagerduty_account": { "subdomain": "pagerduty-subdomain" }, "updated_at": "2024-09-13T10:11:12.000Z" } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/account-mappings/get-account-mappings # List account mappings `GET https://api.pagerduty.com/integration-jira-cloud/accounts_mappings` List existing account mappings. An Account Mapping establishes a connection between a PagerDuty account and a Jira Cloud instance, enabling integration and synchronization between the two platforms. Scoped OAuth requires: `jira_cloud_accounts.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Offset to start pagination search results. Default: `0`. Minimum: 0. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `limit` | integer | | The number of results per page. Default: `25`. Minimum: 1. Maximum: 100. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | ## Response 200 A paginated list of account mappings. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `accounts_mappings` | array of object | | | | `accounts_mappings[].created_at` | string | yes | The time when the account mapping was created. | | `accounts_mappings[].id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `accounts_mappings[].jira_cloud_account` | object | yes | Details of the Jira Cloud instance connected to the PagerDuty account. | | `accounts_mappings[].jira_cloud_account.base_url` | string | yes | The base URL of the Jira Cloud instance, used for API calls and constructing links. | | `accounts_mappings[].pagerduty_account` | object | yes | Details of the PagerDuty account to which the integration is connected. | | `accounts_mappings[].pagerduty_account.subdomain` | string | yes | The unique subdomain of the PagerDuty account, used to identify and access the account (e.g., `acme` in `https://acme.pagerduty.com`). | | `accounts_mappings[].updated_at` | string \| null | | The time when the account mapping was last modified. | | `limit` | integer | | Echoes limit pagination property. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `more` | boolean | | Indicates if there are additional records to return. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `offset` | integer | | Echoes limit pagination property. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `total` | integer \| null | | The total number of records matching the given query. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | Example: Request Example ```json { "accounts_mappings": [ { "created_at": "2024-09-12T12:34:55.000Z", "id": "PIJ90N7", "jira_cloud_account": { "base_url": "https://atlassian-subdomain.atlassian.net" }, "pagerduty_account": { "subdomain": "pagerduty-subdomain" }, "updated_at": "2024-09-13T10:11:12.000Z" } ], "limit": 25, "more": false, "offset": 0, "total": 1 } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/rules/create-rule # Create a rule `POST https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}/rules` Create a new rule. A Rule configures the bidirectional synchronization between Jira issues and PagerDuty incidents. Scoped OAuth requires: `jira_cloud_rules.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Request body (`application/json`) — required The rule to be created. | Field | Type | Required | Description | |---|---|---|---| | `config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `config.jira` | object | yes | Synchronization settings. | | `config.jira.autocreate_jql` | string \| null | yes | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `config.jira.custom_fields` | array \| null | yes | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `config.jira.issue_type` | object | yes | Specifies the Jira issue type to be created or synchronized with PagerDuty incidents. | | `config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `config.jira.issue_type.name` | string | yes | | | `config.jira.priorities` | array \| null | yes | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `config.jira.project` | object | yes | Defines the Jira project where issues will be created or synchronized. | | `config.jira.project.id` | string | yes | | | `config.jira.project.key` | string | yes | | | `config.jira.project.name` | string | yes | | | `config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `config.jira.status_mapping.acknowledged.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.acknowledged.name` | string | yes | | | `config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `config.jira.status_mapping.resolved.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.resolved.name` | string | yes | | | `config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.triggered.name` | string | yes | | | `config.jira.sync_notes_user` | object \| null | yes | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `config.service` | object | yes | The PagerDuty service associated with this rule. | | `config.service.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.service.type` | string | yes | One of: `service_reference`. | | `enabled` | boolean \| null | | Whether the rule is enabled. | | `name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | Example: Request Example ```json { "config": { "jira": { "autocreate_jql": "priority = Highest", "create_issue_on_incident_trigger": true, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" }, { "source_incident_field": "incident_number", "target_issue_field": "customfield_10001", "target_issue_field_name": "PagerDuty Incident Number", "type": "attribute" }, { "target_issue_field": "security", "target_issue_field_name": "Security Level", "type": "jira_value", "value": { "displayName": "Sec Level 1", "id": "10000" } }, { "target_issue_field": "labels", "target_issue_field_name": "Labels", "type": "const", "value": "pagerduty, incident" } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" }, { "jira_id": "3", "pagerduty_id": "PN6RJ21" } ], "project": { "id": "10100", "key": "ITS", "name": "IT Support" }, "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "id": "PBAZLIU", "type": "user_reference" } }, "service": { "id": "PY1OL64", "type": "service_reference" } }, "name": "Critical IT Incidents", "enabled": true } ``` ## Response 201 The rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `account_mapping` | object | yes | Account mapping to which the rule belongs. | | `account_mapping.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `account_mapping.self` | string | yes | The API URL at which the object is accessible. | | `account_mapping.type` | string | yes | One of: `account_mapping_reference`. | | `autocreate_jql_disabled_reason` | string \| null | | If auto-creation using JQL is disabled, this field provides the reason for the disablement. | | `autocreate_jql_disabled_until` | string \| null | | The timestamp until which the auto-creation using JQL feature is disabled. | | `config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `config.jira` | object | yes | Synchronization settings. | | `config.jira.autocreate_jql` | string \| null | | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `config.jira.custom_fields` | array \| null | | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `config.jira.issue_type` | object | yes | Jira issue type to be created or synchronized with PagerDuty incidents. | | `config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `config.jira.issue_type.name` | string | yes | | | `config.jira.priorities` | array \| null | | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `config.jira.project` | object | yes | Jira project where issues will be created or synchronized. | | `config.jira.project.id` | string | yes | Unique identifier for the Jira project. | | `config.jira.project.key` | string | yes | Unique identifier key for the Jira project. | | `config.jira.project.name` | string | yes | | | `config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `config.jira.status_mapping.acknowledged.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.acknowledged.name` | string \| null | | | | `config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `config.jira.status_mapping.resolved.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.resolved.name` | string \| null | | | | `config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.triggered.name` | string | yes | | | `config.jira.sync_notes_user` | object \| null | | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `config.jira.sync_notes_user.email` | string | yes | | | `config.jira.sync_notes_user.html_url` | string \| null | | The URL at which the user is uniquely displayed in the PagerDuty web app. | | `config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.jira.sync_notes_user.name` | string | yes | | | `config.jira.sync_notes_user.self` | string | | The API URL at which the object is accessible. | | `config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `config.service` | object | yes | The PagerDuty service associated with this rule. | | `config.service.html_url` | string \| null | | The URL at which the service is uniquely displayed in the PagerDuty web app. | | `config.service.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.service.self` | string | | The API URL at which the object is accessible. | | `config.service.summary` | string | yes | The name or summary of the PagerDuty service. | | `config.service.type` | string | yes | One of: `service_reference`. | | `created_at` | string | yes | The time when the rule was created. | | `enabled` | boolean | | Indicates if the rule is enabled. | | `id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | | `updated_at` | string \| null | | The time when the rule was last modified. | Example: Response Example ```json { "account_mapping": { "id": "PIJ90N7", "self": "https://api.pagerduty.com/integration-jira-cloud/account_mappings/PIJ90N7", "type": "accounts_mapping_reference" }, "config": { "jira": { "autocreate_jql": "priority = Highest", "create_issue_on_incident_trigger": true, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" }, { "source_incident_field": "incident_number", "target_issue_field": "customfield_10001", "target_issue_field_name": "PagerDuty Incident Number", "type": "attribute" }, { "target_issue_field": "security", "target_issue_field_name": "Security Level", "type": "jira_value", "value": { "displayName": "Sec Level 1", "id": "10000" } }, { "target_issue_field": "labels", "target_issue_field_name": "Labels", "type": "const", "value": "pagerduty, incident" } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" }, { "jira_id": "3", "pagerduty_id": "PN6RJ21" } ], "project": { "id": "10100", "key": "ITS", "name": "IT Support" }, "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "email": "e.greenholt@example.com", "html_url": "https://subdomain.pagerduty.com/users/PBAZLIU", "id": "PBAZLIU", "name": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PBAZLIU", "type": "user_reference" }, "version": 1 }, "service": { "html_url": "https://api.pagerduty.com/services/PY1OL64", "id": "PY1OL64", "self": "https://api.pagerduty.com/services/PY1OL64", "summary": "Main Web Application", "type": "service_reference" } }, "created_at": "2023-09-01T12:00:00.000Z", "id": "PF9KMXH", "name": "Critical IT Incidents", "enabled": true, "updated_at": "2023-09-01T12:00:00.000Z" } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/rules/delete-rule # Delete a rule `DELETE https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}/rules/{rule_id}` Delete an existing rule. Once a rule is deleted, the synchronization between PagerDuty Incidents and Jira Issues linked by the rule stops. Scoped OAuth requires: `jira_cloud_rules.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rule_id` | string (PagerDuty Id) | yes | The ID of the account rule. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Response 204 The rule was deleted successfully. ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/rules/get-rule # Get a rule `GET https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}/rules/{rule_id}` Get detailed information about an existing rule. A Rule configures the bidirectional synchronization between Jira issues and PagerDuty incidents. Scoped OAuth requires: `jira_cloud_rules.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rule_id` | string (PagerDuty Id) | yes | The ID of the account rule. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Response 200 The rule requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `account_mapping` | object | yes | Account mapping to which the rule belongs. | | `account_mapping.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `account_mapping.self` | string | yes | The API URL at which the object is accessible. | | `account_mapping.type` | string | yes | One of: `account_mapping_reference`. | | `autocreate_jql_disabled_reason` | string \| null | | If auto-creation using JQL is disabled, this field provides the reason for the disablement. | | `autocreate_jql_disabled_until` | string \| null | | The timestamp until which the auto-creation using JQL feature is disabled. | | `config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `config.jira` | object | yes | Synchronization settings. | | `config.jira.autocreate_jql` | string \| null | | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `config.jira.custom_fields` | array \| null | | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `config.jira.issue_type` | object | yes | Jira issue type to be created or synchronized with PagerDuty incidents. | | `config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `config.jira.issue_type.name` | string | yes | | | `config.jira.priorities` | array \| null | | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `config.jira.project` | object | yes | Jira project where issues will be created or synchronized. | | `config.jira.project.id` | string | yes | Unique identifier for the Jira project. | | `config.jira.project.key` | string | yes | Unique identifier key for the Jira project. | | `config.jira.project.name` | string | yes | | | `config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `config.jira.status_mapping.acknowledged.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.acknowledged.name` | string \| null | | | | `config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `config.jira.status_mapping.resolved.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.resolved.name` | string \| null | | | | `config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.triggered.name` | string | yes | | | `config.jira.sync_notes_user` | object \| null | | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `config.jira.sync_notes_user.email` | string | yes | | | `config.jira.sync_notes_user.html_url` | string \| null | | The URL at which the user is uniquely displayed in the PagerDuty web app. | | `config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.jira.sync_notes_user.name` | string | yes | | | `config.jira.sync_notes_user.self` | string | | The API URL at which the object is accessible. | | `config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `config.service` | object | yes | The PagerDuty service associated with this rule. | | `config.service.html_url` | string \| null | | The URL at which the service is uniquely displayed in the PagerDuty web app. | | `config.service.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.service.self` | string | | The API URL at which the object is accessible. | | `config.service.summary` | string | yes | The name or summary of the PagerDuty service. | | `config.service.type` | string | yes | One of: `service_reference`. | | `created_at` | string | yes | The time when the rule was created. | | `enabled` | boolean | | Indicates if the rule is enabled. | | `id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | | `updated_at` | string \| null | | The time when the rule was last modified. | Example: Response Example ```json { "account_mapping": { "id": "PIJ90N7", "self": "https://api.pagerduty.com/integration-jira-cloud/account_mappings/PIJ90N7", "type": "accounts_mapping_reference" }, "config": { "jira": { "autocreate_jql": "priority = High", "create_issue_on_incident_trigger": true, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" } ], "project": { "id": "10100", "key": "ITS", "name": "IT Support" }, "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "email": "e.greenholt@example.com", "html_url": "https://subdomain.pagerduty.com/users/PBAZLIU", "id": "PBAZLIU", "name": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PBAZLIU", "type": "user_reference" } }, "service": { "html_url": "https://api.pagerduty.com/services/PY1OL64", "id": "PY1OL64", "self": "https://api.pagerduty.com/services/PY1OL64", "summary": "Main Web Application", "type": "service_reference" }, "version": 1 }, "created_at": "2023-09-01T12:00:00.000Z", "id": "PF9KMXH", "name": "Critical IT Incidents", "enabled": true, "updated_at": "2023-09-01T12:00:00.000Z" } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/rules/get-rules # List rules `GET https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}/rules` List existing rules for a specific account mapping. A Rule configures the bidirectional synchronization between Jira issues and PagerDuty incidents. Scoped OAuth requires: `jira_cloud_rules.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Offset to start pagination search results. Default: `0`. Minimum: 0. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `limit` | integer | | The number of results per page. Default: `25`. Minimum: 1. Maximum: 100. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | ## Response 200 A paginated list of rules. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `more` | boolean | | Indicates if there are additional records to return. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `offset` | integer | | Echoes limit pagination property. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | | `rules` | array of object | | | | `rules[].account_mapping` | object | yes | Account mapping to which the rule belongs. | | `rules[].account_mapping.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rules[].account_mapping.self` | string | yes | The API URL at which the object is accessible. | | `rules[].account_mapping.type` | string | yes | One of: `account_mapping_reference`. | | `rules[].autocreate_jql_disabled_reason` | string \| null | | If auto-creation using JQL is disabled, this field provides the reason for the disablement. | | `rules[].autocreate_jql_disabled_until` | string \| null | | The timestamp until which the auto-creation using JQL feature is disabled. | | `rules[].config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `rules[].config.jira` | object | yes | Synchronization settings. | | `rules[].config.jira.autocreate_jql` | string \| null | | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `rules[].config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `rules[].config.jira.custom_fields` | array \| null | | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `rules[].config.jira.issue_type` | object | yes | Jira issue type to be created or synchronized with PagerDuty incidents. | | `rules[].config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `rules[].config.jira.issue_type.name` | string | yes | | | `rules[].config.jira.priorities` | array \| null | | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `rules[].config.jira.project` | object | yes | Jira project where issues will be created or synchronized. | | `rules[].config.jira.project.id` | string | yes | Unique identifier for the Jira project. | | `rules[].config.jira.project.key` | string | yes | Unique identifier key for the Jira project. | | `rules[].config.jira.project.name` | string | yes | | | `rules[].config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `rules[].config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `rules[].config.jira.status_mapping.acknowledged.id` | string \| null | | Unique identifier for the Jira status. | | `rules[].config.jira.status_mapping.acknowledged.name` | string \| null | | | | `rules[].config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `rules[].config.jira.status_mapping.resolved.id` | string \| null | | Unique identifier for the Jira status. | | `rules[].config.jira.status_mapping.resolved.name` | string \| null | | | | `rules[].config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `rules[].config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `rules[].config.jira.status_mapping.triggered.name` | string | yes | | | `rules[].config.jira.sync_notes_user` | object \| null | | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `rules[].config.jira.sync_notes_user.email` | string | yes | | | `rules[].config.jira.sync_notes_user.html_url` | string \| null | | The URL at which the user is uniquely displayed in the PagerDuty web app. | | `rules[].config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rules[].config.jira.sync_notes_user.name` | string | yes | | | `rules[].config.jira.sync_notes_user.self` | string | | The API URL at which the object is accessible. | | `rules[].config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `rules[].config.service` | object | yes | The PagerDuty service associated with this rule. | | `rules[].config.service.html_url` | string \| null | | The URL at which the service is uniquely displayed in the PagerDuty web app. | | `rules[].config.service.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rules[].config.service.self` | string | | The API URL at which the object is accessible. | | `rules[].config.service.summary` | string | yes | The name or summary of the PagerDuty service. | | `rules[].config.service.type` | string | yes | One of: `service_reference`. | | `rules[].created_at` | string | yes | The time when the rule was created. | | `rules[].enabled` | boolean | | Indicates if the rule is enabled. | | `rules[].id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rules[].name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | | `rules[].updated_at` | string \| null | | The time when the rule was last modified. | | `total` | integer \| null | | The total number of records matching the given query. [See our Pagination Docs for more information](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTU4-pagination). | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "rules": [ { "account_mapping": { "id": "PIJ90N7", "self": "https://api.pagerduty.com/integration-jira-cloud/account_mappings/PIJ90N7", "type": "accounts_mapping_reference" }, "config": { "jira": { "autocreate_jql": "priority = High", "create_issue_on_incident_trigger": true, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" } ], "project": { "id": "10100", "key": "ITS", "name": "IT Support" }, "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "email": "e.greenholt@example.com", "html_url": "https://subdomain.pagerduty.com/users/PBAZLIU", "id": "PBAZLIU", "name": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PBAZLIU", "type": "user_reference" } }, "service": { "html_url": "https://api.pagerduty.com/services/PY1OL64", "id": "PY1OL64", "self": "https://api.pagerduty.com/services/PY1OL64", "summary": "Main Web Application", "type": "service_reference" }, "version": 1 }, "created_at": "2023-09-01T12:00:00.000Z", "id": "PF9KMXH", "name": "Critical Incidents to Jira", "updated_at": "2023-09-01T12:00:00.000Z" } ], "total": 1 } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-cloud/rules/update-rule # Update a rule `PUT https://api.pagerduty.com/integration-jira-cloud/accounts_mappings/{id}/rules/{rule_id}` Update an existing rule. A Rule configures the bidirectional synchronization between Jira issues and PagerDuty incidents. Scoped OAuth requires: `jira_cloud_rules.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. - **bearerAuth** (http) — HTTP bearer. ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string (PagerDuty Id) | yes | The ID of the account mapping. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `rule_id` | string (PagerDuty Id) | yes | The ID of the account rule. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | ## Request body (`application/json`) — required The rule to be updated. | Field | Type | Required | Description | |---|---|---|---| | `config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `config.jira` | object | yes | Synchronization settings. | | `config.jira.autocreate_jql` | string \| null | yes | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `config.jira.custom_fields` | array \| null | yes | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `config.jira.issue_type` | object | yes | Specifies the Jira issue type to be created or synchronized with PagerDuty incidents. | | `config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `config.jira.issue_type.name` | string | yes | | | `config.jira.priorities` | array \| null | yes | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `config.jira.status_mapping.acknowledged.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.acknowledged.name` | string | yes | | | `config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `config.jira.status_mapping.resolved.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.resolved.name` | string | yes | | | `config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.triggered.name` | string | yes | | | `config.jira.sync_notes_user` | object \| null | yes | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `enabled` | boolean \| null | | Indicates if the rule is enabled. | | `name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | Example: Request Example ```json { "config": { "jira": { "autocreate_jql": "priority in (Highest, High)", "create_issue_on_incident_trigger": false, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" }, { "source_incident_field": "incident_number", "target_issue_field": "customfield_10001", "target_issue_field_name": "PagerDuty Incident Number", "type": "attribute" }, { "target_issue_field": "security", "target_issue_field_name": "Security Level", "type": "jira_value", "value": { "displayName": "Sec Level 1", "id": "10000" } } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" }, { "jira_id": "3", "pagerduty_id": "PN6RJ21" } ], "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "id": "PBAZLIU", "type": "user_reference" } } }, "name": "Critical IT Incidents", "enabled": true } ``` ## Response 200 The rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `account_mapping` | object | yes | Account mapping to which the rule belongs. | | `account_mapping.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `account_mapping.self` | string | yes | The API URL at which the object is accessible. | | `account_mapping.type` | string | yes | One of: `account_mapping_reference`. | | `autocreate_jql_disabled_reason` | string \| null | | If auto-creation using JQL is disabled, this field provides the reason for the disablement. | | `autocreate_jql_disabled_until` | string \| null | | The timestamp until which the auto-creation using JQL feature is disabled. | | `config` | object | yes | Configuration for bidirectional synchronization between Jira issues and PagerDuty incidents. | | `config.jira` | object | yes | Synchronization settings. | | `config.jira.autocreate_jql` | string \| null | | JQL query to automatically create PagerDuty incidents when matching Jira issues are created. Leave empty to disable this feature. | | `config.jira.create_issue_on_incident_trigger` | boolean | yes | When enabled, automatically creates a Jira issue whenever a PagerDuty incident is triggered. Default: `false`. | | `config.jira.custom_fields` | array \| null | | Defines how Jira fields are populated when a Jira Issue is created from a PagerDuty Incident. | | `config.jira.issue_type` | object | yes | Jira issue type to be created or synchronized with PagerDuty incidents. | | `config.jira.issue_type.id` | string | yes | Unique identifier for the Jira issue type. | | `config.jira.issue_type.name` | string | yes | | | `config.jira.priorities` | array \| null | | Maps PagerDuty incident priorities to Jira issue priorities for synchronization. | | `config.jira.project` | object | yes | Jira project where issues will be created or synchronized. | | `config.jira.project.id` | string | yes | Unique identifier for the Jira project. | | `config.jira.project.key` | string | yes | Unique identifier key for the Jira project. | | `config.jira.project.name` | string | yes | | | `config.jira.status_mapping` | object | yes | Maps PagerDuty incident statuses to corresponding Jira issue statuses for synchronization. | | `config.jira.status_mapping.acknowledged` | object \| null | | Optional Jira status that maps to the PagerDuty `acknowledged` status. | | `config.jira.status_mapping.acknowledged.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.acknowledged.name` | string \| null | | | | `config.jira.status_mapping.resolved` | object \| null | | Optional Jira status that maps to the PagerDuty `resolved` status. | | `config.jira.status_mapping.resolved.id` | string \| null | | Unique identifier for the Jira status. | | `config.jira.status_mapping.resolved.name` | string \| null | | | | `config.jira.status_mapping.triggered` | object | yes | Jira status that maps to the PagerDuty `triggered` status. | | `config.jira.status_mapping.triggered.id` | string | yes | Unique identifier for the Jira status. | | `config.jira.status_mapping.triggered.name` | string | yes | | | `config.jira.sync_notes_user` | object \| null | | PagerDuty user for syncing notes and comments between Jira issues and PagerDuty incidents. If not provided, note synchronization is disabled. | | `config.jira.sync_notes_user.email` | string | yes | | | `config.jira.sync_notes_user.html_url` | string \| null | | The URL at which the user is uniquely displayed in the PagerDuty web app. | | `config.jira.sync_notes_user.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.jira.sync_notes_user.name` | string | yes | | | `config.jira.sync_notes_user.self` | string | | The API URL at which the object is accessible. | | `config.jira.sync_notes_user.type` | string | yes | One of: `user_reference`. | | `config.service` | object | yes | The PagerDuty service associated with this rule. | | `config.service.html_url` | string \| null | | The URL at which the service is uniquely displayed in the PagerDuty web app. | | `config.service.id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `config.service.self` | string | | The API URL at which the object is accessible. | | `config.service.summary` | string | yes | The name or summary of the PagerDuty service. | | `config.service.type` | string | yes | One of: `service_reference`. | | `created_at` | string | yes | The time when the rule was created. | | `enabled` | boolean | | Indicates if the rule is enabled. | | `id` | string (PagerDuty Id) | yes | Unique identifier. Pattern: `^(P[0-9A-Z]{6}\|Q[0-9A-Z]{13})$`. | | `name` | string | yes | The name of the rule. Max length: 100. Pattern: `^[^\x00-\x1F\x7F<>]+$`. | | `updated_at` | string \| null | | The time when the rule was last modified. | Example: Response Example ```json { "account_mapping": { "id": "PIJ90N7", "self": "https://api.pagerduty.com/integration-jira-cloud/account_mappings/PIJ90N7", "type": "accounts_mapping_reference" }, "config": { "jira": { "autocreate_jql": "priority in (Highest, High)", "create_issue_on_incident_trigger": false, "custom_fields": [ { "source_incident_field": "incident_description", "target_issue_field": "description", "target_issue_field_name": "Description", "type": "attribute" }, { "source_incident_field": "incident_number", "target_issue_field": "customfield_10001", "target_issue_field_name": "PagerDuty Incident Number", "type": "attribute" }, { "target_issue_field": "security", "target_issue_field_name": "Security Level", "type": "jira_value", "value": { "displayName": "Sec Level 1", "id": "10000" } } ], "issue_type": { "id": "10001", "name": "Incident" }, "priorities": [ { "jira_id": "1", "pagerduty_id": "PUS0KTE" }, { "jira_id": "2", "pagerduty_id": "PQFCJER" }, { "jira_id": "3", "pagerduty_id": "PN6RJ21" } ], "project": { "id": "10100", "key": "ITS", "name": "IT Support" }, "status_mapping": { "acknowledged": { "id": "2", "name": "In Progress" }, "resolved": { "id": "3", "name": "Resolved" }, "triggered": { "id": "1", "name": "Open" } }, "sync_notes_user": { "email": "e.greenholt@example.com", "html_url": "https://subdomain.pagerduty.com/users/PBAZLIU", "id": "PBAZLIU", "name": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PBAZLIU", "type": "user_reference" }, "version": 1 }, "service": { "html_url": "https://api.pagerduty.com/services/PY1OL64", "id": "PY1OL64", "self": "https://api.pagerduty.com/services/PY1OL64", "summary": "Main Web Application", "type": "service_reference" } }, "created_at": "2023-09-01T12:00:00.000Z", "id": "PF9KMXH", "name": "Critical IT Incidents", "enabled": true, "updated_at": "2023-09-01T12:00:00.000Z" } ``` ## Response 400 Caller provided invalid arguments. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2001, "errors": [ "Invalid value for field 'name'" ], "message": "Invalid Input Provided" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. ## Response 403 Caller is not authorized to manage the requested resource. While the authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Forbidden" } } ``` ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "code": 2020, "message": "Rate Limit Exceeded" } } ``` ## Response 500 Internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Error code. | | `error.errors` | array of string | | Error details. | | `error.message` | string | | Error message. | Example: Response Example ```json { "error": { "errors": [], "message": "Internal server error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-service/rules/create-rule # Create a rule `POST https://app.pagerduty.com/integration-jira-service/rules` Creates a rule. The maximum number of rules a user could have is 2000. If the limit is reached, API will respond with an error. > ### Action required! > > Make sure that all required PagerDuty and Jira webhooks are present. You can do this by clicking **Check webhooks** button on the *Rules* page of the PagerDuty Jira application ## Authorization - **BearerToken** (http) — HTTP bearer. PagerDuty OAuth user Access Token The developer should obtain a valid user-based bearer token by performing Classic User OAuth by following our public documentation: https://developer.pagerduty.com/docs/b2a19cce2867a-classic-user-o-auth ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `x-pagerduty-jira-signature` | string | yes | Connected Jira instance signature token This header contains a signature token that validates the connection between PagerDuty and a specific Jira instance. It must be included in all API requests. > ### Obtaining the signature token > > 1. Send an authenticated GET request to your Jira instance: `GET /plugins/servlet/pagerduty/sign` > > 2. The endpoint returns a JSON response containing the signature: `{ "signature": "eyJ0eXAiOiJK..." }` > > 3. Use the returned signature value in the x-pagerduty-jira-signature header for all subsequent API calls. Note: Signature token is valid for 15 minutes after generation. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | | | `rule.name` | string | yes | A name of the rule. Max length: 128. | | `rule.enabled` | boolean | yes | Indicates if the rule is enabled. Default: `false`. | | `rule.config` | object | yes | Contatins an object which describes a rule. | | `rule.config.sync_comments` | boolean | | Indicates if comments should be synchronized. Default: `false`. | | `rule.config.services` | array of object | | An array of the PagerDuty services. Min items: 1. | | `rule.config.services[].id` | string | yes | | | `rule.config.services[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.services[].type` | string | yes | One of: `service_reference`. | | `rule.config.services[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.services[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.projects` | array of object \| null | | An array of Jira projects. Min items: 1. | | `rule.config.projects[].id` | string | yes | | | `rule.config.projects[].key` | string | yes | | | `rule.config.projects[].label` | string | yes | | | `rule.config.projects[].icon` | string (url) | yes | | | `rule.config.projects[].html_url` | string (url) | yes | | | `rule.config.issue_types` | array of object \| null | | An array of Jira issue types. Min items: 1. | | `rule.config.issue_types[].id` | string | yes | | | `rule.config.issue_types[].label` | string | yes | | | `rule.config.issue_types[].icon` | string (url) | yes | | | `rule.config.autocreate_issues` | boolean | | Indicates if automatic Jira issue creation is enabled. Default: `false`. | | `rule.config.autocreate_issues_config` | array of object | | An array of rules that are applied when automatic Jira issue creation is enabled. | | `rule.config.autocreate_issues_config[].condition` | object | | | | `rule.config.autocreate_issues_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to create a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].id` | string | yes | | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].type` | string | yes | One of: `priority_reference`. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.autocreate_issues_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.autocreate_issues_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].target_project` | object \| null | | Jira Project. | | `rule.config.autocreate_issues_config[].target_project.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.key` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.icon` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_project.html_url` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_issue_type` | object \| null | | Jira Issue Type. | | `rule.config.autocreate_issues_config[].target_issue_type.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.autocreate_incidents` | boolean | | Indicates if automatic PagerDuty incident creation is enabled. Default: `false`. | | `rule.config.autocreate_incidents_config` | array of object | | An array of rules that are applied when automatic PagerDuty incident creation is enabled. | | `rule.config.autocreate_incidents_config[].jql` | string | yes | Rule will be applied, when issue matches the JQL. | | `rule.config.autocreate_incidents_config[].on_create` | boolean | | Apply the rule on issue creation. Default: `false`. | | `rule.config.autocreate_incidents_config[].on_update` | boolean | | Apply the rule on issue update. Default: `false`. | | `rule.config.autocreate_incidents_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].target_service` | object | | The reference to the service. | | `rule.config.autocreate_incidents_config[].target_service.id` | string | yes | | | `rule.config.autocreate_incidents_config[].target_service.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_incidents_config[].target_service.type` | string | yes | One of: `service_reference`. | | `rule.config.autocreate_incidents_config[].target_service.self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_incidents_config[].target_service.html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.react_on_incident_event` | boolean | | Indicates if reaction on PagerDuty incident updates is enabled. Default: `false`. | | `rule.config.react_on_incident_event_config` | array of object | | An array of rules that are applied to the Jira issue when reaction on PagerDuty incident updates is enabled. | | `rule.config.react_on_incident_event_config[].condition` | object | | | | `rule.config.react_on_incident_event_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to update a Jira issue. | | `rule.config.react_on_incident_event_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. Same fields as `rule.config.autocreate_issues_config[].condition.pd_priorities` above. | | `rule.config.react_on_incident_event_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.react_on_incident_event_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].target_project` | object \| null | | Jira Project. Same fields as `rule.config.autocreate_issues_config[].target_project` above. | | `rule.config.react_on_incident_event_config[].target_issue_type` | object | | Issue Type, which should set on the issue. | | `rule.config.react_on_incident_event_config[].target_issue_type.id` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.label` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.react_on_issue_status_change` | boolean | | Indicates if reaction on Jira issue status change is enabled. Default: `false`. | | `rule.config.react_on_issue_status_change_config` | array of object | | An array of rules that are applied to the PagerDuty incident when reaction on Jira issue status change is enabled. | | `rule.config.react_on_issue_status_change_config[].jira_statuses` | array of object | | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].id` | string | yes | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].label` | string | | | | `rule.config.react_on_issue_status_change_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_issue_status_change_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.created_at` | string (date-time) | yes | The date/time rule was created. Read-only. | Example: Request Example ```json { "rule": { "name": "Sample Rule", "created_at": "2020-06-02T12:42:37Z", "enabled": true, "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } } ``` ## Response 200 The rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | Same fields as `rule` above. | Example: Response Example ```json { "rule": { "name": "Sample Rule", "created_at": "2020-06-02T12:42:37Z", "enabled": true, "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Invalid input provided ```json { "error": { "message": "Invalid Input Provided" } } ``` Example: Validation error ```json { "error": { "errors": [ "Name can't be blank" ], "message": "Invalid Input Provided" } } ``` Example: Malformed json ```json { "error": { "message": "Malformed json" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Authorization Error ```json { "error": { "message": "Authorization error" } } ``` ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Unprocessable Entity ```json { "error": { "message": "Unprocessable Entity" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-service/rules/delete-rule # Delete a rule `DELETE https://app.pagerduty.com/integration-jira-service/rules/{id}` Delete an existing rule. > ### Action required! > > Make sure that all required PagerDuty and Jira webhooks are present. You can do this by clicking **Check webhooks** button on the *Rules* page of the PagerDuty Jira application ## Authorization - **BearerToken** (http) — HTTP bearer. PagerDuty OAuth user Access Token The developer should obtain a valid user-based bearer token by performing Classic User OAuth by following our public documentation: https://developer.pagerduty.com/docs/b2a19cce2867a-classic-user-o-auth ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `x-pagerduty-jira-signature` | string | yes | Connected Jira instance signature token This header contains a signature token that validates the connection between PagerDuty and a specific Jira instance. It must be included in all API requests. > ### Obtaining the signature token > > 1. Send an authenticated GET request to your Jira instance: `GET /plugins/servlet/pagerduty/sign` > > 2. The endpoint returns a JSON response containing the signature: `{ "signature": "eyJ0eXAiOiJK..." }` > > 3. Use the returned signature value in the x-pagerduty-jira-signature header for all subsequent API calls. Note: Signature token is valid for 15 minutes after generation. | ## Response 204 The rule was deleted successfully. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Authorization Error ```json { "error": { "message": "Authorization error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-service/rules/get-rule # Get a rule `GET https://app.pagerduty.com/integration-jira-service/rules/{id}` Get details about an existing rule. ## Authorization - **BearerToken** (http) — HTTP bearer. PagerDuty OAuth user Access Token The developer should obtain a valid user-based bearer token by performing Classic User OAuth by following our public documentation: https://developer.pagerduty.com/docs/b2a19cce2867a-classic-user-o-auth ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `x-pagerduty-jira-signature` | string | yes | Connected Jira instance signature token This header contains a signature token that validates the connection between PagerDuty and a specific Jira instance. It must be included in all API requests. > ### Obtaining the signature token > > 1. Send an authenticated GET request to your Jira instance: `GET /plugins/servlet/pagerduty/sign` > > 2. The endpoint returns a JSON response containing the signature: `{ "signature": "eyJ0eXAiOiJK..." }` > > 3. Use the returned signature value in the x-pagerduty-jira-signature header for all subsequent API calls. Note: Signature token is valid for 15 minutes after generation. | ## Response 200 The rule requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | | | `rule.name` | string | yes | A name of the rule. Max length: 128. | | `rule.enabled` | boolean | yes | Indicates if the rule is enabled. Default: `false`. | | `rule.config` | object | yes | Contatins an object which describes a rule. | | `rule.config.sync_comments` | boolean | | Indicates if comments should be synchronized. Default: `false`. | | `rule.config.services` | array of object | | An array of the PagerDuty services. Min items: 1. | | `rule.config.services[].id` | string | yes | | | `rule.config.services[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.services[].type` | string | yes | One of: `service_reference`. | | `rule.config.services[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.services[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.projects` | array of object \| null | | An array of Jira projects. Min items: 1. | | `rule.config.projects[].id` | string | yes | | | `rule.config.projects[].key` | string | yes | | | `rule.config.projects[].label` | string | yes | | | `rule.config.projects[].icon` | string (url) | yes | | | `rule.config.projects[].html_url` | string (url) | yes | | | `rule.config.issue_types` | array of object \| null | | An array of Jira issue types. Min items: 1. | | `rule.config.issue_types[].id` | string | yes | | | `rule.config.issue_types[].label` | string | yes | | | `rule.config.issue_types[].icon` | string (url) | yes | | | `rule.config.autocreate_issues` | boolean | | Indicates if automatic Jira issue creation is enabled. Default: `false`. | | `rule.config.autocreate_issues_config` | array of object | | An array of rules that are applied when automatic Jira issue creation is enabled. | | `rule.config.autocreate_issues_config[].condition` | object | | | | `rule.config.autocreate_issues_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to create a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].id` | string | yes | | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].type` | string | yes | One of: `priority_reference`. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.autocreate_issues_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.autocreate_issues_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].target_project` | object \| null | | Jira Project. | | `rule.config.autocreate_issues_config[].target_project.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.key` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.icon` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_project.html_url` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_issue_type` | object \| null | | Jira Issue Type. | | `rule.config.autocreate_issues_config[].target_issue_type.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.autocreate_incidents` | boolean | | Indicates if automatic PagerDuty incident creation is enabled. Default: `false`. | | `rule.config.autocreate_incidents_config` | array of object | | An array of rules that are applied when automatic PagerDuty incident creation is enabled. | | `rule.config.autocreate_incidents_config[].jql` | string | yes | Rule will be applied, when issue matches the JQL. | | `rule.config.autocreate_incidents_config[].on_create` | boolean | | Apply the rule on issue creation. Default: `false`. | | `rule.config.autocreate_incidents_config[].on_update` | boolean | | Apply the rule on issue update. Default: `false`. | | `rule.config.autocreate_incidents_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].target_service` | object | | The reference to the service. | | `rule.config.autocreate_incidents_config[].target_service.id` | string | yes | | | `rule.config.autocreate_incidents_config[].target_service.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_incidents_config[].target_service.type` | string | yes | One of: `service_reference`. | | `rule.config.autocreate_incidents_config[].target_service.self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_incidents_config[].target_service.html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.react_on_incident_event` | boolean | | Indicates if reaction on PagerDuty incident updates is enabled. Default: `false`. | | `rule.config.react_on_incident_event_config` | array of object | | An array of rules that are applied to the Jira issue when reaction on PagerDuty incident updates is enabled. | | `rule.config.react_on_incident_event_config[].condition` | object | | | | `rule.config.react_on_incident_event_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to update a Jira issue. | | `rule.config.react_on_incident_event_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. Same fields as `rule.config.autocreate_issues_config[].condition.pd_priorities` above. | | `rule.config.react_on_incident_event_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.react_on_incident_event_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].target_project` | object \| null | | Jira Project. Same fields as `rule.config.autocreate_issues_config[].target_project` above. | | `rule.config.react_on_incident_event_config[].target_issue_type` | object | | Issue Type, which should set on the issue. | | `rule.config.react_on_incident_event_config[].target_issue_type.id` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.label` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.react_on_issue_status_change` | boolean | | Indicates if reaction on Jira issue status change is enabled. Default: `false`. | | `rule.config.react_on_issue_status_change_config` | array of object | | An array of rules that are applied to the PagerDuty incident when reaction on Jira issue status change is enabled. | | `rule.config.react_on_issue_status_change_config[].jira_statuses` | array of object | | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].id` | string | yes | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].label` | string | | | | `rule.config.react_on_issue_status_change_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_issue_status_change_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.created_at` | string (date-time) | yes | The date/time rule was created. Read-only. | Example: Response Example ```json { "rule": { "name": "Sample Rule", "created_at": "2020-06-02T12:42:37Z", "enabled": true, "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Authorization Error ```json { "error": { "message": "Authorization error" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Not Found ```json { "error": { "message": "Record not found" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-service/rules/get-rules # List rules `GET https://app.pagerduty.com/integration-jira-service/rules` Returns a list of rules. ## Authorization - **BearerToken** (http) — HTTP bearer. PagerDuty OAuth user Access Token The developer should obtain a valid user-based bearer token by performing Classic User OAuth by following our public documentation: https://developer.pagerduty.com/docs/b2a19cce2867a-classic-user-o-auth ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `total` | boolean | | Returns the total number of records matched by the query if enabled. Default: `false`. | | `limit` | integer | | Set the maximum number of results matched by the query. Default: `25`. Minimum: 1. Maximum: 100. | | `offset` | integer | | The number of items to skip before starting to collect the result set. Default: `0`. Minimum: 0. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `x-pagerduty-jira-signature` | string | yes | Connected Jira instance signature token This header contains a signature token that validates the connection between PagerDuty and a specific Jira instance. It must be included in all API requests. > ### Obtaining the signature token > > 1. Send an authenticated GET request to your Jira instance: `GET /plugins/servlet/pagerduty/sign` > > 2. The endpoint returns a JSON response containing the signature: `{ "signature": "eyJ0eXAiOiJK..." }` > > 3. Use the returned signature value in the x-pagerduty-jira-signature header for all subsequent API calls. Note: Signature token is valid for 15 minutes after generation. | ## Response 200 A paginated list of rules. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | yes | Echoes offset pagination property. Read-only. Default: `0`. | | `limit` | integer | yes | Echoes limit pagination property. Read-only. Default: `25`. Minimum: 0. Maximum: 100. | | `more` | boolean | yes | Indicates if there are additional records to return. Read-only. Default: `false`. | | `total` | integer \| null | yes | The total number of records matching the given query. Read-only. Default: `null`. | | `rules` | array of object | yes | | | `rules[].name` | string | yes | A name of the rule. Max length: 128. | | `rules[].enabled` | boolean | yes | Indicates if the rule is enabled. Default: `false`. | | `rules[].config` | object | yes | Contatins an object which describes a rule. | | `rules[].config.sync_comments` | boolean | | Indicates if comments should be synchronized. Default: `false`. | | `rules[].config.services` | array of object | | An array of the PagerDuty services. Min items: 1. | | `rules[].config.services[].id` | string | yes | | | `rules[].config.services[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rules[].config.services[].type` | string | yes | One of: `service_reference`. | | `rules[].config.services[].self` | string (url) | | The API show URL at which the object is accessible. | | `rules[].config.services[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rules[].config.projects` | array of object \| null | | An array of Jira projects. Min items: 1. | | `rules[].config.projects[].id` | string | yes | | | `rules[].config.projects[].key` | string | yes | | | `rules[].config.projects[].label` | string | yes | | | `rules[].config.projects[].icon` | string (url) | yes | | | `rules[].config.projects[].html_url` | string (url) | yes | | | `rules[].config.issue_types` | array of object \| null | | An array of Jira issue types. Min items: 1. | | `rules[].config.issue_types[].id` | string | yes | | | `rules[].config.issue_types[].label` | string | yes | | | `rules[].config.issue_types[].icon` | string (url) | yes | | | `rules[].config.autocreate_issues` | boolean | | Indicates if automatic Jira issue creation is enabled. Default: `false`. | | `rules[].config.autocreate_issues_config` | array of object | | An array of rules that are applied when automatic Jira issue creation is enabled. | | `rules[].config.autocreate_issues_config[].condition` | object | | | | `rules[].config.autocreate_issues_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to create a Jira issue. | | `rules[].config.autocreate_issues_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. | | `rules[].config.autocreate_issues_config[].condition.pd_priorities[].id` | string | yes | | | `rules[].config.autocreate_issues_config[].condition.pd_priorities[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rules[].config.autocreate_issues_config[].condition.pd_priorities[].type` | string | yes | One of: `priority_reference`. | | `rules[].config.autocreate_issues_config[].condition.pd_priorities[].self` | string (url) | | The API show URL at which the object is accessible. | | `rules[].config.autocreate_issues_config[].condition.pd_priorities[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rules[].config.autocreate_issues_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rules[].config.autocreate_issues_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rules[].config.autocreate_issues_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rules[].config.autocreate_issues_config[].target_project` | object \| null | | Jira Project. | | `rules[].config.autocreate_issues_config[].target_project.id` | string | yes | | | `rules[].config.autocreate_issues_config[].target_project.key` | string | yes | | | `rules[].config.autocreate_issues_config[].target_project.label` | string | yes | | | `rules[].config.autocreate_issues_config[].target_project.icon` | string (url) | yes | | | `rules[].config.autocreate_issues_config[].target_project.html_url` | string (url) | yes | | | `rules[].config.autocreate_issues_config[].target_issue_type` | object \| null | | Jira Issue Type. | | `rules[].config.autocreate_issues_config[].target_issue_type.id` | string | yes | | | `rules[].config.autocreate_issues_config[].target_issue_type.label` | string | yes | | | `rules[].config.autocreate_issues_config[].target_issue_type.icon` | string (url) | yes | | | `rules[].config.autocreate_incidents` | boolean | | Indicates if automatic PagerDuty incident creation is enabled. Default: `false`. | | `rules[].config.autocreate_incidents_config` | array of object | | An array of rules that are applied when automatic PagerDuty incident creation is enabled. | | `rules[].config.autocreate_incidents_config[].jql` | string | yes | Rule will be applied, when issue matches the JQL. | | `rules[].config.autocreate_incidents_config[].on_create` | boolean | | Apply the rule on issue creation. Default: `false`. | | `rules[].config.autocreate_incidents_config[].on_update` | boolean | | Apply the rule on issue update. Default: `false`. | | `rules[].config.autocreate_incidents_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rules[].config.autocreate_incidents_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rules[].config.autocreate_incidents_config[].target_service` | object | | The reference to the service. | | `rules[].config.autocreate_incidents_config[].target_service.id` | string | yes | | | `rules[].config.autocreate_incidents_config[].target_service.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rules[].config.autocreate_incidents_config[].target_service.type` | string | yes | One of: `service_reference`. | | `rules[].config.autocreate_incidents_config[].target_service.self` | string (url) | | The API show URL at which the object is accessible. | | `rules[].config.autocreate_incidents_config[].target_service.html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rules[].config.react_on_incident_event` | boolean | | Indicates if reaction on PagerDuty incident updates is enabled. Default: `false`. | | `rules[].config.react_on_incident_event_config` | array of object | | An array of rules that are applied to the Jira issue when reaction on PagerDuty incident updates is enabled. | | `rules[].config.react_on_incident_event_config[].condition` | object | | | | `rules[].config.react_on_incident_event_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to update a Jira issue. | | `rules[].config.react_on_incident_event_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. Same fields as `rules[].config.autocreate_issues_config[].condition.pd_priorities` above. | | `rules[].config.react_on_incident_event_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rules[].config.react_on_incident_event_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rules[].config.react_on_incident_event_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rules[].config.react_on_incident_event_config[].target_project` | object \| null | | Jira Project. Same fields as `rules[].config.autocreate_issues_config[].target_project` above. | | `rules[].config.react_on_incident_event_config[].target_issue_type` | object | | Issue Type, which should set on the issue. | | `rules[].config.react_on_incident_event_config[].target_issue_type.id` | string | yes | | | `rules[].config.react_on_incident_event_config[].target_issue_type.label` | string | yes | | | `rules[].config.react_on_incident_event_config[].target_issue_type.icon` | string (url) | yes | | | `rules[].config.react_on_issue_status_change` | boolean | | Indicates if reaction on Jira issue status change is enabled. Default: `false`. | | `rules[].config.react_on_issue_status_change_config` | array of object | | An array of rules that are applied to the PagerDuty incident when reaction on Jira issue status change is enabled. | | `rules[].config.react_on_issue_status_change_config[].jira_statuses` | array of object | | | | `rules[].config.react_on_issue_status_change_config[].jira_statuses[].id` | string | yes | | | `rules[].config.react_on_issue_status_change_config[].jira_statuses[].label` | string | | | | `rules[].config.react_on_issue_status_change_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rules[].config.react_on_issue_status_change_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rules[].created_at` | string (date-time) | yes | The date/time rule was created. Read-only. | Example: Response Example ```json { "rules": [ { "name": "Sample Rule", "enabled": true, "created_at": "2020-06-02T12:42:37Z", "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } ], "limit": 1, "offset": 0, "more": true, "total": 99 } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Authorization Error ```json { "error": { "message": "Authorization error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-jira-service/rules/update-rule # Update a rule `PUT https://app.pagerduty.com/integration-jira-service/rules/{id}` Update an existing rule. > ### Action required! > > Make sure that all required PagerDuty and Jira webhooks are present. You can do this by clicking **Check webhooks** button on the *Rules* page of the PagerDuty Jira application ## Authorization - **BearerToken** (http) — HTTP bearer. PagerDuty OAuth user Access Token The developer should obtain a valid user-based bearer token by performing Classic User OAuth by following our public documentation: https://developer.pagerduty.com/docs/b2a19cce2867a-classic-user-o-auth ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `x-pagerduty-jira-signature` | string | yes | Connected Jira instance signature token This header contains a signature token that validates the connection between PagerDuty and a specific Jira instance. It must be included in all API requests. > ### Obtaining the signature token > > 1. Send an authenticated GET request to your Jira instance: `GET /plugins/servlet/pagerduty/sign` > > 2. The endpoint returns a JSON response containing the signature: `{ "signature": "eyJ0eXAiOiJK..." }` > > 3. Use the returned signature value in the x-pagerduty-jira-signature header for all subsequent API calls. Note: Signature token is valid for 15 minutes after generation. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | | | `rule.name` | string | yes | A name of the rule. Max length: 128. | | `rule.enabled` | boolean | yes | Indicates if the rule is enabled. Default: `false`. | | `rule.config` | object | yes | Contatins an object which describes a rule. | | `rule.config.sync_comments` | boolean | | Indicates if comments should be synchronized. Default: `false`. | | `rule.config.services` | array of object | | An array of the PagerDuty services. Min items: 1. | | `rule.config.services[].id` | string | yes | | | `rule.config.services[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.services[].type` | string | yes | One of: `service_reference`. | | `rule.config.services[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.services[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.projects` | array of object \| null | | An array of Jira projects. Min items: 1. | | `rule.config.projects[].id` | string | yes | | | `rule.config.projects[].key` | string | yes | | | `rule.config.projects[].label` | string | yes | | | `rule.config.projects[].icon` | string (url) | yes | | | `rule.config.projects[].html_url` | string (url) | yes | | | `rule.config.issue_types` | array of object \| null | | An array of Jira issue types. Min items: 1. | | `rule.config.issue_types[].id` | string | yes | | | `rule.config.issue_types[].label` | string | yes | | | `rule.config.issue_types[].icon` | string (url) | yes | | | `rule.config.autocreate_issues` | boolean | | Indicates if automatic Jira issue creation is enabled. Default: `false`. | | `rule.config.autocreate_issues_config` | array of object | | An array of rules that are applied when automatic Jira issue creation is enabled. | | `rule.config.autocreate_issues_config[].condition` | object | | | | `rule.config.autocreate_issues_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to create a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].id` | string | yes | | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].type` | string | yes | One of: `priority_reference`. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_issues_config[].condition.pd_priorities[].html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.autocreate_issues_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.autocreate_issues_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_issues_config[].target_project` | object \| null | | Jira Project. | | `rule.config.autocreate_issues_config[].target_project.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.key` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_project.icon` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_project.html_url` | string (url) | yes | | | `rule.config.autocreate_issues_config[].target_issue_type` | object \| null | | Jira Issue Type. | | `rule.config.autocreate_issues_config[].target_issue_type.id` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.label` | string | yes | | | `rule.config.autocreate_issues_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.autocreate_incidents` | boolean | | Indicates if automatic PagerDuty incident creation is enabled. Default: `false`. | | `rule.config.autocreate_incidents_config` | array of object | | An array of rules that are applied when automatic PagerDuty incident creation is enabled. | | `rule.config.autocreate_incidents_config[].jql` | string | yes | Rule will be applied, when issue matches the JQL. | | `rule.config.autocreate_incidents_config[].on_create` | boolean | | Apply the rule on issue creation. Default: `false`. | | `rule.config.autocreate_incidents_config[].on_update` | boolean | | Apply the rule on issue update. Default: `false`. | | `rule.config.autocreate_incidents_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.autocreate_incidents_config[].target_service` | object | | The reference to the service. | | `rule.config.autocreate_incidents_config[].target_service.id` | string | yes | | | `rule.config.autocreate_incidents_config[].target_service.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `rule.config.autocreate_incidents_config[].target_service.type` | string | yes | One of: `service_reference`. | | `rule.config.autocreate_incidents_config[].target_service.self` | string (url) | | The API show URL at which the object is accessible. | | `rule.config.autocreate_incidents_config[].target_service.html_url` | string \| null (url) | | A URL at which the entity is uniquely displayed in the Web app. | | `rule.config.react_on_incident_event` | boolean | | Indicates if reaction on PagerDuty incident updates is enabled. Default: `false`. | | `rule.config.react_on_incident_event_config` | array of object | | An array of rules that are applied to the Jira issue when reaction on PagerDuty incident updates is enabled. | | `rule.config.react_on_incident_event_config[].condition` | object | | | | `rule.config.react_on_incident_event_config[].condition.pd_events` | array of string | | A list of PagerDuty incident actions which should be matched to update a Jira issue. | | `rule.config.react_on_incident_event_config[].condition.pd_priorities` | array of object | | A list of PagerDuty priorities that should be matched to create/update a Jira issue. Same fields as `rule.config.autocreate_issues_config[].condition.pd_priorities` above. | | `rule.config.react_on_incident_event_config[].condition.pd_urgency` | string \| null | | A PagerDuty urgency that should be matched to create/update a Jira issue. One of: `high`, `low`. | | `rule.config.react_on_incident_event_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.config.react_on_incident_event_config[].target_project` | object \| null | | Jira Project. Same fields as `rule.config.autocreate_issues_config[].target_project` above. | | `rule.config.react_on_incident_event_config[].target_issue_type` | object | | Issue Type, which should set on the issue. | | `rule.config.react_on_incident_event_config[].target_issue_type.id` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.label` | string | yes | | | `rule.config.react_on_incident_event_config[].target_issue_type.icon` | string (url) | yes | | | `rule.config.react_on_issue_status_change` | boolean | | Indicates if reaction on Jira issue status change is enabled. Default: `false`. | | `rule.config.react_on_issue_status_change_config` | array of object | | An array of rules that are applied to the PagerDuty incident when reaction on Jira issue status change is enabled. | | `rule.config.react_on_issue_status_change_config[].jira_statuses` | array of object | | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].id` | string | yes | | | `rule.config.react_on_issue_status_change_config[].jira_statuses[].label` | string | | | | `rule.config.react_on_issue_status_change_config[].actions` | array of object | | Actions that applied when the rule will be executed. | | `rule.config.react_on_issue_status_change_config[].actions_params` | object | | Configuration of actions that applied when the rule will be executed. | | `rule.created_at` | string (date-time) | yes | The date/time rule was created. Read-only. | Example: Request Example ```json { "rule": { "name": "Sample Rule", "created_at": "2020-06-02T12:42:37Z", "enabled": true, "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } } ``` ## Response 200 The rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | Same fields as `rule` above. | Example: Response Example ```json { "rule": { "name": "Sample Rule", "created_at": "2020-06-02T12:42:37Z", "enabled": true, "config": { "sync_comments": true, "services": [ { "id": "PLW70S2", "type": "service_reference", "label": "Jira Integration", "html_url": "https://subdomain.pagerduty.com/service-directory/PLW70S2" }, { "id": "PR5R1T1", "type": "service_reference", "label": "Jira Performance Tests", "html_url": "https://subdomain.pagerduty.com/service-directory/PR5R1T1" } ], "projects": [ { "key": "PD", "id": "10000", "label": "PagerDuty", "html_url": "http://jira.example.com/projects/PD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" } ], "issue_types": [ { "id": "10002", "icon": "http://jira.example.com/images/icons/issuetypes/story.svg", "label": "Story" }, { "id": "10003", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype", "label": "Task" }, { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" } ], "autocreate_incidents": true, "autocreate_incidents_config": [ { "jql": "issuetype=Bug", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false }, { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" }, "jira_field_set_labels": [ { "label": "Service name", "icon": "pd", "key": "incident.service.summary" } ], "pd_set_priority": { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" } } }, { "jql": "issuetype=Story", "on_create": true, "on_update": true, "target_service": { "id": "PR5R1T1", "type": "service_reference" }, "actions": [ { "key": "jira_field_set_labels", "label": "Set Labels", "icon": "jira", "isDisabled": false }, { "key": "pd_set_priority", "label": "Set Incident Priority", "icon": "pd", "isDisabled": false } ], "actions_params": { "jira_field_set_labels": [ { "label": "LinkedToPagerduty", "key": "LinkedToPagerduty", "icon": "text" } ], "pd_set_priority": { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" } } } ], "autocreate_issues": true, "autocreate_issues_config": [ { "condition": { "pd_events": [ "incident.trigger", "incident.acknowledge", "incident.unacknowledge", "incident.resolve", "incident.escalate", "incident.assign", "incident.delegate", "incident.trigger_manually" ], "pd_urgency": "high", "pd_priorities": [] }, "target_project": null, "target_issue_type": null, "actions": [ { "key": "jira_append_description", "label": "Add description", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_append_description": [ { "label": "Incident title", "icon": "pd", "key": "incident.title" }, { "label": "Incident number", "icon": "pd", "key": "incident.incident_number" }, { "label": "Incident ID", "icon": "pd", "key": "incident.id" }, { "label": "Description", "icon": "pd", "key": "log_entries.channel.details" }, { "label": "Status", "icon": "pd", "key": "incident.status" }, { "label": "Created At", "icon": "pd", "key": "incident.created_at" }, { "label": "Service name", "icon": "pd", "key": "incident.service.summary" }, { "label": "Escalation policy name", "icon": "pd", "key": "incident.escalation_policy.summary" }, { "label": "Impacted services", "icon": "pd", "key": "incident.impacted_services.name" }, { "label": "Incident URL", "icon": "pd", "key": "incident.html_url" }, { "label": "Acknowledgements", "icon": "pd", "key": "incident.acknowledgements.acknowledger.name" }, { "label": "Urgency", "icon": "pd", "key": "incident.urgency" }, { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" }, { "label": "Priority", "icon": "pd", "key": "incident.priority.summary" }, { "label": "Last changed by", "icon": "pd", "key": "incident.last_status_change_by.summary" }, { "label": "Last changed at", "icon": "pd", "key": "incident.last_status_change_at" }, { "label": "And my custom text", "key": "And my custom text", "icon": "text" } ] } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "high", "pd_priorities": [ { "id": "PZQ39X0", "type": "priority_reference", "label": "P1", "html_url": null, "icon": "rect_color_ff4500" }, { "id": "POV67SK", "type": "priority_reference", "label": "P2", "html_url": null, "icon": "rect_color_f59331" } ] }, "target_project": { "key": "HD", "id": "10001", "label": "Helpdesk", "html_url": "http://jira.example.com/projects/HD", "icon": "http://jira.example.com/secure/projectavatar?avatarId=10324" }, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Highest", "icon": "http://jira.example.com/images/icons/priorities/highest.svg", "name": "Highest", "id": "1" } } }, { "condition": { "pd_events": [ "incident.trigger" ], "pd_urgency": "low", "pd_priorities": [ { "id": "P0A95OH", "type": "priority_reference", "label": "P3", "html_url": null, "icon": "rect_color_359d54" }, { "id": "PCNJ47O", "type": "priority_reference", "label": "P4", "html_url": null, "icon": "rect_color_76ec7f" }, { "id": "PRSM238", "type": "priority_reference", "label": "P5", "html_url": null, "icon": "rect_color_f4f4f4" } ] }, "target_project": null, "target_issue_type": { "id": "10004", "icon": "http://jira.example.com/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype", "label": "Bug" }, "actions": [ { "key": "jira_field_set_priority", "label": "Set Priority", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_priority": { "label": "Low", "icon": "http://jira.example.com/images/icons/priorities/low.svg", "name": "Low", "id": "4" } } } ], "react_on_incident_event": true, "react_on_incident_event_config": [ { "condition": { "pd_events": [ "incident.acknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "3", "label": "In Progress" } } }, { "condition": { "pd_events": [ "incident.unacknowledge" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10000", "label": "To Do" } } }, { "condition": { "pd_events": [ "incident.resolve" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_change_status", "label": "Change Jira issue status to", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_change_status": { "id": "10001", "label": "Done" } } }, { "condition": { "pd_events": [ "incident.assign" ], "pd_urgency": "high", "pd_priorities": [] }, "actions": [ { "key": "jira_field_set_assignee", "label": "Set Assignee", "icon": "jira", "isDisabled": false } ], "actions_params": { "jira_field_set_assignee": { "label": "Incident assignee", "icon": "pd", "key": "incident.assignee" } } } ], "react_on_issue_status_change": true, "react_on_issue_status_change_config": [ { "jira_statuses": [ { "id": "3", "label": "In Progress" } ], "actions": [ { "key": "pd_acknowledge", "label": "Acknowledge Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10001", "label": "Done" } ], "actions": [ { "key": "pd_resolve", "label": "Resolve Incident", "icon": "pd", "isDisabled": false } ] }, { "jira_statuses": [ { "id": "10000", "label": "To Do" } ], "actions": [ { "key": "pd_add_responders", "label": "Add responders", "icon": "pd", "isDisabled": false } ], "actions_params": { "pd_add_responders": [ { "id": "PDU13T4", "type": "user_reference", "email": "user1@example.com", "label": "User 1", "html_url": "https://subdomain.pagerduty.com/users/PDU13T4", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" }, { "id": "PKH7YP2", "type": "user_reference", "email": "user2@example.com", "label": "User 2", "html_url": "https://subdomain.pagerduty.com/users/PKH7YP2", "icon": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png" } ] } } ] } } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Authorization Error ```json { "error": { "message": "Authorization error" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | Example: Not Found ```json { "error": { "message": "Record not found" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-ms-teams/ms-teams-dedicated-chats/create-dedicated-chat # Create a Dedicated Chat `POST https://api.pagerduty.com/integration-ms-teams/incidents/{incident_id}/dedicated_chat` Creates a Microsoft Teams Group Chat for the specified Incident and returns its details. > ### Important > > Make sure that your PagerDuty account is connected to your MS Teams tenant and your > PagerDuty user is linked to your MS Teams user. You can do this on the MS Teams > add-on page in your PagerDuty account or by interacting with the PagerDuty bot > in Microsoft Teams. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `mst_tenant_id` | string | yes | ID of the Microsoft Teams tenant connected to PagerDuty. | | `owner_pd_user_id` | string | | PagerDuty User ID of the user whose MS Teams account should own the chat. Defaults to the requesting user. | | `chat` | object | | Details of the Group Chat to be created in Microsoft Teams. | | `chat.name` | string | | Name of the Group Chat in Microsoft Teams. | | `events` | string | | Preset name for the type of Incident updates to send to the chat. Valid values: highlights_only, status_updates_only, all_updates, no_updates. Defaults to all_updates. | Example: Request Example ```json { "mst_tenant_id": "dd649b90-2b30-45cb-a264-1130134c625e", "chat": { "name": "Incident #1234: Server Room is on Fire" }, "events": "all_updates" } ``` ## Response 201 Returns details of the Group Chat created in Microsoft Teams. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `chat` | object | yes | Microsoft Teams Group Chat details. | | `chat.name` | string | yes | Name of the Group Chat in Microsoft Teams. | | `chat.url` | string | yes | URL to open the Group Chat in Microsoft Teams. | Example: Response Example ```json { "chat": { "name": "Incident #1234: Server Room is on Fire", "url": "https://teams.microsoft.com/l/chat/19%3Ameeting_xyz%40thread.v2/0" } } ``` ## Response 400 The request was malformed or invalid. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Bad Request ```json { "error": { "message": "Bad Request" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to access the requested resource. While the authentication is valid, the authenticated user does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` ## Response 409 A dedicated chat already exists for the specified Incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Conflict ```json { "error": { "message": "The incident chat group already exists." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-ms-teams/ms-teams-dedicated-chats/delete-dedicated-chat # Delete a Dedicated Chat `DELETE https://api.pagerduty.com/integration-ms-teams/incidents/{incident_id}/dedicated_chat` Deletes the Microsoft Teams Group Chat for the specified Incident. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Group Chat was deleted successfully. ## Response 400 The request was malformed or invalid. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Bad Request ```json { "error": { "message": "Bad Request" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to access the requested resource. While the authentication is valid, the authenticated user does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-ms-teams/ms-teams-dedicated-chats/get-dedicated-chat # Get a Dedicated Chat `GET https://api.pagerduty.com/integration-ms-teams/incidents/{incident_id}/dedicated_chat` Retrieves the Microsoft Teams Group Chat details for the specified Incident. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Returns the Group Chat details for the specified Incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `chat` | object | yes | Microsoft Teams Group Chat details. | | `chat.name` | string | yes | Name of the Group Chat in Microsoft Teams. | | `chat.url` | string | yes | URL to open the Group Chat in Microsoft Teams. | | `tenant_id` | string | yes | MS Teams Tenant ID associated with the chat. | Example: Response Example ```json { "chat": { "name": "Incident #1234: Server Room is on Fire", "url": "https://teams.microsoft.com/l/chat/19%3Ameeting_xyz%40thread.v2/0" }, "tenant_id": "dd649b90-2b30-45cb-a264-1130134c625e" } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to access the requested resource. While the authentication is valid, the authenticated user does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-ms-teams/ms-teams-meetings/create-meeting # Create a Meeting `POST https://api.pagerduty.com/integration-ms-teams/incidents/{incident_id}/meeting` Creates a meeting in Microsoft Teams and attaches it to the conference bridge details of the Incident. > ### Important > > Make sure that your PagerDuty account is connected to your MS Teams team and your > PagerDuty user is linked to your MS Teams user. You can do this on the MS Teams > add-on page in your PagerDuty account or by interacting with the PagerDuty bot > in Microsoft Teams. > > Also, to create meetings you have to be authorized in Microsoft Graph. Type > `graphAuth` in a personal chat with the PagerDuty bot to pass the authorization. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `mst_team_id` | string | yes | ID of a Microsoft Teams team that is connected to PagerDuty. | | `meeting` | object | | Details of a meeting to be created in Microsoft Teams. | | `meeting.name` | string | | Default: `Incident title`. | Example: Request Example ```json { "mst_team_id": "19:TjtRuEN_HvOh-WspuZRFl6o4SaKgQO_wuA1qGdxQ1VU1@thread.tacv2", "meeting": { "name": "Server Room is on Fire" } } ``` ## Response 201 Returns details of the meeting created in Microsoft Teams. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `meeting` | object | yes | Microsoft Teams meeting details. | | `meeting.name` | string | | | | `meeting.url` | string | | | Example: Response Example ```json { "meeting": { "name": "Server Room is on Fire", "url": "https://teams.microsoft.com/l/meetup-join/19%3ameeting_TllZTMjMyZTk4NWMtMWUyYi00ZTRmLUtMzU2YTg0MTQzNjMz%40thread.v2/0" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to access the requested resource. While the authentication is valid, the authenticated user does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-connections/create-connection # Create a Slack Connection `POST https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections` Creates a Slack Connection > ### Important > > Make sure that your PagerDuty account is linked to your Slack workspace and your PagerDuty user is linked to your Slack user. You can do this on the Slack extension page in your PagerDuty account. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. Scoped OAuth requires: `services.read users.read webhook_subscriptions.write priorities.read incidents.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `slack_team_id` | string | yes | Slack team (workspace) id. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | | | | `slack_connection.channel_id` | string | yes | | | `slack_connection.source_id` | string | yes | | | `slack_connection.source_type` | string | yes | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connection.notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connection.config` | object | yes | Item of the Slack connection that contains configuration options (filters). | | `slack_connection.config.events` | array of string | | Configuration item of the Slack connection allows you to subscribe to different type of events. | | `slack_connection.config.urgency` | string \| null | | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. | | `slack_connection.config.priorities` | array \| null | | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. | Example: Request Example ```json { "slack_connection": { "source_id": "A1234B5", "source_type": "team_reference", "channel_id": "A123B456C7D", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 201 Returns created Slack Connection. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | yes | | | `slack_connection.id` | string | | | | `slack_connection.source_id` | string | | | | `slack_connection.source_name` | string | | | | `slack_connection.source_type` | string | | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connection.channel_id` | string | | | | `slack_connection.channel_name` | string | | | | `slack_connection.notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connection.config` | object | | Item of the Slack connection that contains configuration options (filters). Same fields as `slack_connection.config` above. | Example: Response Example ```json { "slack_connection": { "id": "A12BCDE", "source_id": "A1234B5", "source_name": "test_team", "source_type": "team_reference", "channel_id": "A123B456C7D", "channel_name": "random", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Validation Error ```json { "error": { "errors": [ "Name can't be blank" ], "message": "Invalid Input Provided" } } ``` Example: Invalid channel_id provided ```json { "error": { "message": "Unable to update a Slack Connection: Slack channel name fetch failed" } } ``` Example: Malformed JSON ```json { "error": { "message": "Malformed JSON" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-connections/delete-connection # Delete a Slack Connection `DELETE https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections/{connection_id}` Delete an existing Slack Connection. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. Scoped OAuth requires: `services.read users.read incidents.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `slack_team_id` | string | yes | Slack team (workspace) id. | | `connection_id` | string | yes | Slack connection id. | ## Response 204 The Slack Connection was deleted successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | yes | | | `slack_connection.id` | string | | | | `slack_connection.source_id` | string | | | | `slack_connection.source_name` | string | | | | `slack_connection.source_type` | string | | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connection.channel_id` | string | | | | `slack_connection.channel_name` | string | | | | `slack_connection.notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connection.config` | object | | Item of the Slack connection that contains configuration options (filters). | | `slack_connection.config.events` | array of string | | Configuration item of the Slack connection allows you to subscribe to different type of events. | | `slack_connection.config.urgency` | string \| null | | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. | | `slack_connection.config.priorities` | array \| null | | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. | Example: Response Example ```json { "slack_connection": { "id": "A12BCDE", "source_id": "A1234B5", "source_name": "test_team", "source_type": "team_reference", "channel_id": "A123B456C7D", "channel_name": "random", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-connections/get-connection # Get a Slack Connection `GET https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections/{connection_id}` Get details about an existing Slack Connection. > **Note:** For accounts using the New Slack Configuration, the `config.urgency` and `config.priorities` fields reflect the values last written through the REST API. If the connection's channel conditions were subsequently modified through the Slack web UI, those changes will not be reflected in these fields. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. Scoped OAuth requires: `users.read incidents.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `slack_team_id` | string | yes | Slack team (workspace) id. | | `connection_id` | string | yes | Slack connection id. | ## Response 200 The Slack Connection requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | yes | | | `slack_connection.id` | string | | | | `slack_connection.source_id` | string | | | | `slack_connection.source_name` | string | | | | `slack_connection.source_type` | string | | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connection.channel_id` | string | | | | `slack_connection.channel_name` | string | | | | `slack_connection.notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connection.config` | object | | Item of the Slack connection that contains configuration options (filters). | | `slack_connection.config.events` | array of string | | Configuration item of the Slack connection allows you to subscribe to different type of events. | | `slack_connection.config.urgency` | string \| null | | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. | | `slack_connection.config.priorities` | array \| null | | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. | Example: Response Example ```json { "slack_connection": { "id": "A12BCDE", "source_id": "A1234B5", "source_name": "test_service", "source_type": "service_reference", "channel_id": "A123B456C7D", "channel_name": "random", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-connections/get-connections # List Slack Connections `GET https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections` Returns a list of Slack Connections. > **Note:** For accounts using the New Slack Configuration, the `config.urgency` and `config.priorities` fields reflect the values last written through the REST API. If the connection's channel conditions were subsequently modified through the Slack web UI, those changes will not be reflected in these fields. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. Scoped OAuth requires: `users.read incidents.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `slack_team_id` | string | yes | Slack team (workspace) id. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Set the maximum number of results matched by the query. Default: `50`. Minimum: 1. Maximum: 100. | | `offset` | integer | | The number of items to skip before starting to collect the result set. Default: `0`. Minimum: 0. | ## Response 200 A set of Slack Connections matching the request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `slack_connections` | array of object | yes | | | `slack_connections[].id` | string | | | | `slack_connections[].source_id` | string | | | | `slack_connections[].source_name` | string | | | | `slack_connections[].source_type` | string | | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connections[].channel_id` | string | | | | `slack_connections[].channel_name` | string | | | | `slack_connections[].notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connections[].config` | object | | Item of the Slack connection that contains configuration options (filters). | | `slack_connections[].config.events` | array of string | | Configuration item of the Slack connection allows you to subscribe to different type of events. | | `slack_connections[].config.urgency` | string \| null | | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. | | `slack_connections[].config.priorities` | array \| null | | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. | | `offset` | integer | yes | Echoes offset pagination property. Read-only. Default: `0`. | | `limit` | integer | yes | Echoes limit pagination property. Read-only. Default: `50`. Minimum: 0. Maximum: 100. | | `more` | boolean | yes | Indicates if there are additional records to return. Read-only. Default: `false`. | | `total` | integer | yes | The total number of records matching the given query. Read-only. Default: `null`. | Example: Response Example ```json { "slack_connections": [ { "id": "A12BCDE", "source_id": "A1234B5", "source_name": "test_team", "source_type": "team_reference", "channel_id": "A123B456C7D", "channel_name": "random", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } ], "limit": 1, "offset": 0, "more": true, "total": 99 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-connections/update-connection # Update a Slack Connection `PUT https://app.pagerduty.com/integration-slack/workspaces/{slack_team_id}/connections/{connection_id}` Update an existing Slack Connection. > **Note:** For accounts using the New Slack Configuration, submitting this request rebuilds the channel's PCL (PagerDuty Condition Language) filter from the `config.urgency` and `config.priorities` values in the request payload. Any PCL conditions previously configured through the Slack web UI will be overridden. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. Scoped OAuth requires: `services.read users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `slack_team_id` | string | yes | Slack team (workspace) id. | | `connection_id` | string | yes | Slack connection id. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | yes | | | `slack_connection.id` | string | | | | `slack_connection.source_id` | string | | | | `slack_connection.source_name` | string | | | | `slack_connection.source_type` | string | | Configuration item of the Slack connection that indicates what PagerDuty source would be used for the connection (can be Service or Team). One of: `service_reference`, `team_reference`. | | `slack_connection.channel_id` | string | | | | `slack_connection.channel_name` | string | | | | `slack_connection.notification_type` | string | | Configuration item of the Slack connection that indicates how Slack message will be formatted (can be `responder` or `stakeholder`) One of: `responder`, `stakeholder`. Default: `responder`. | | `slack_connection.config` | object | | Item of the Slack connection that contains configuration options (filters). | | `slack_connection.config.events` | array of string | | Configuration item of the Slack connection allows you to subscribe to different type of events. | | `slack_connection.config.urgency` | string \| null | | Configuration item of the Slack connection allows you to filter events by urgency. One of: `high`, `low`, `null`. | | `slack_connection.config.priorities` | array \| null | | Configuration item of the Slack connection that allows you to filter events by priorities. If set to 'null', the connection accepts events of any priority, including those without a specified priority. If set to an empty array, only events without a specific priority are allowed. Otherwise, event filtering adheres to the specific priority codes provided in the array, and the special code 'no_priority' can also be included in the array. | Example: Request Example ```json { "slack_connection": { "source_id": "A1234B5", "source_type": "team_reference", "channel_id": "A123B456C7D", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 200 Returns updated Slack Connection. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `slack_connection` | object | yes | Same fields as `slack_connection` above. | Example: Response Example ```json { "slack_connection": { "id": "A12BCDE", "source_id": "A1234B5", "source_name": "test_team", "source_type": "team_reference", "channel_id": "A123B456C7D", "channel_name": "random", "notification_type": "responder", "config": { "events": [ "incident.triggered", "incident.acknowledged", "incident.escalated", "incident.resolved", "incident.reassigned", "incident.annotated", "incident.unacknowledged", "incident.delegated", "incident.priority_updated", "incident.responder.added", "incident.responder.replied", "incident.status_update_published" ], "priorities": [ "ABCDEF1", "AB1CDE2" ], "urgency": null } } } ``` ## Response 400 Caller provided invalid arguments. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Invalid payload provided ```json { "error": { "message": "The payload is invalid." } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-dedicated-channels/create-dedicated-channel # Create a Slack Dedicated Channel `POST https://api.pagerduty.com/integration-slack/incidents/{incident_id}/dedicated_channel` Creates an incident's slack dedicated channel. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | | | `channel.name` | string | | | | `channel.slack_team_id` | string | | | | `channel.privacy` | string | | One of: `private`, `public`. | Example: Request Example ```json { "channel": { "name": "dedicated", "privacy": "public", "slack_team_id": "T0123456789" } } ``` ## Response 201 Returns created Slack Dedicated Channel. Headers: | Header | Type | Description | |---|---|---| | `Location` | string | The path to get the new incident dedicated channel info | ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | | | `channel.id` | string | | | | `channel.name` | string | | | | `channel.slack_team_id` | string | | | | `channel.link` | string | | | | `channel.deep_link` | string | | | | `warnings` | array of string | | List of unblocking events that can possibly occur durring the channel creation. | Example: Response Example ```json { "channel": { "id": "C0123456789", "name": "dedicated", "slack_team_id": "T0123456789", "link": "https://slack.com/app_redirect?channel=C0123456789&team=T0123456789", "deep_link": "slack://channel?team=T0123456789&id=C0123456789" } } ``` ## Response 400 Caller provided invalid arguments. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Invalid payload provided ```json { "error": { "message": "The payload is invalid." } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 422 The request could not be performed successfully, because some validations failed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: UnprocessableEntity ```json { "error": { "message": "UnprocessableEntity" } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-dedicated-channels/get-dedicated-channel # Get a Slack Dedicated Channel `GET https://api.pagerduty.com/integration-slack/incidents/{incident_id}/dedicated_channel` Returns an incident's slack dedicated channel. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Response 200 The incident slack dedicated channel. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | | | `channel.id` | string | | | | `channel.name` | string | | | | `channel.slack_team_id` | string | | | | `channel.link` | string | | | | `channel.deep_link` | string | | | Example: Response Example ```json { "channel": { "id": "C0123456789", "name": "dedicated", "slack_team_id": "T0123456789", "link": "https://slack.com/app_redirect?channel=C0123456789&team=T0123456789", "deep_link": "slack://channel?team=T0123456789&id=C0123456789" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-dedicated-channels/remove-dedicated-channel # Remove a Slack Dedicated Channel `DELETE https://api.pagerduty.com/integration-slack/incidents/{incident_id}/dedicated_channel` Removes an incident's slack dedicated channel. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Response 204 The incident slack dedicated channel was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-notification-channels/create-notification-channel # Create a Slack Notification Channel `POST https://api.pagerduty.com/integration-slack/incidents/{incident_id}/notification_channels` Creates an incident's slack notification channel. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | | | `channel.id` | string | | | | `channel.slack_team_id` | string | | | Example: Request Example ```json { "channel": { "id": "C0123456789", "slack_team_id": "T0123456789" } } ``` ## Response 201 Returns linked Slack Notification Channel. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | | | `channel.id` | string | | | | `channel.name` | string | | | | `channel.slack_team_id` | string | | | | `channel.link` | string | | | | `channel.deep_link` | string | | | | `warnings` | array of string | | List of unblocking events that can possibly occur durring the channel linking process. | Example: Response Example ```json { "channel": { "id": "C0123456789", "name": "notification", "slack_team_id": "T0123456789", "link": "https://slack.com/app_redirect?channel=C0123456789&team=T0123456789", "deep_link": "slack://channel?team=T0123456789&id=C0123456789" } } ``` ## Response 400 Caller provided invalid arguments. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Invalid payload provided ```json { "error": { "message": "The payload is invalid." } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 422 The request could not be performed successfully, because some validations failed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: UnprocessableEntity ```json { "error": { "message": "UnprocessableEntity" } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-notification-channels/get-notification-channels # List Notification Channels `GET https://api.pagerduty.com/integration-slack/incidents/{incident_id}/notification_channels` Returns an incident's list of slack notification channels. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Response 200 The incident's list of slack notification channels. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `channels` | array of object | yes | | | `channels[].id` | string | | | | `channels[].name` | string | | | | `channels[].slack_team_id` | string | | | | `channels[].link` | string | | | | `channels[].deep_link` | string | | | Example: Response Example ```json { "channels": [ { "id": "C0123456789", "name": "notification1", "slack_team_id": "T0123456789", "link": "https://slack.com/app_redirect?channel=C0123456789&team=T0123456789", "deep_link": "slack://channel?team=T0123456789&id=C0123456789" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-notification-channels/remove-notification-channel # Remove a Slack Notification Channel `DELETE https://api.pagerduty.com/integration-slack/incidents/{incident_id}/notification_channels/{channel_id}` Unlinks an incident's slack notification channel. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | | `channel_id` | string | yes | Slack Channel ID. | ## Response 204 The incident slack notification channel was unlinked successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/integration-slack/slack-notification-channels/update-notification-channel # Update Slack Notification Channels `PUT https://api.pagerduty.com/integration-slack/incidents/{incident_id}/notification_channels` Update an incident's slack notification channels. > ### Important > > Ensure you are using a User API Token or a User OAuth Token to make requests to this API. Also, check that your user has necessary > permissions (Owner or Global Admin). See https://developer.pagerduty.com/docs/rest-api-v2/authentication/ for the > details. ## Authorization - **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=` - **bearerAuth** (http) — HTTP bearer. The Bearer access token with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `incident_id` | string | yes | PagerDuty Incident ID. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `channels` | array of object | yes | | | `channels[].id` | string | | | | `channels[].slack_team_id` | string | | | Example: Request Example ```json { "channels": [ { "id": "C0123456789", "slack_team_id": "T0123456789" }, { "id": "C0987654321", "slack_team_id": "T0987654321" } ] } ``` ## Response 200 Returns the new list of Slack Notification Channel. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `channels` | array of object | yes | | | `channels[].id` | string | | | | `channels[].name` | string | | | | `channels[].slack_team_id` | string | | | | `channels[].link` | string | | | | `channels[].deep_link` | string | | | | `warnings` | array of string | | List of failed operations, when the success is only partial. | Example: Response Example ```json { "channels": [ { "id": "C0123456789", "name": "notification1", "slack_team_id": "T0123456789", "link": "https://slack.com/app_redirect?channel=C0123456789&team=T0123456789", "deep_link": "slack://channel?team=T0123456789&id=C0123456789" }, { "id": "C0987654321", "name": "notification2", "slack_team_id": "T0987654321", "link": "https://slack.com/app_redirect?channel=C0987654321&team=T0987654321", "deep_link": "slack://channel?team=T0987654321&id=C0987654321" } ] } ``` ## Response 400 Caller provided invalid arguments. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Invalid payload provided ```json { "error": { "message": "The payload is invalid." } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Unauthorized ```json { "error": { "message": "Unauthorized" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Forbidden ```json { "error": { "message": "Forbidden" } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Not Found ```json { "error": { "message": "Not Found" } } ``` Example: Invalid Workspace ```json { "error": { "message": "The PagerDuty has not been connected to this workspace. Please complete the installation and try again." } } ``` ## Response 422 The request could not be performed successfully, because some validations failed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: UnprocessableEntity ```json { "error": { "message": "UnprocessableEntity" } } ``` ## Response 500 Request resulted in internal server error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | Error message string. Read-only. | Example: Internal Server Error ```json { "error": { "message": "Internal Server Error" } } ``` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/mcp/pagerduty-mcp-api/mcp-root # MCP Endpoint `POST https://mcp.pagerduty.com/mcp` The root MCP path for all JSON-RPC requests. ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Authorization` | string | yes | Should contain the API key or OAuth token to authorize the request. Format: `Token token=` or `Bearer ` Pattern: `^(Token token=[A-Za-z0-9]+\|Bearer [A-Za-z0-9]+)$`. | | `Accept` | string | yes | MCP clients must accept both application/json and text/event-stream. One of: `application/json, text/event-stream`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `jsonrpc` | string | yes | The JSON-RPC version, must be "2.0". One of: `2.0`. [See the MCP specification for more information](https://modelcontextprotocol.io/specification/2025-06-18/basic#requests). | | `id` | one of: integer \| string | yes | A unique ID for this request. [See the MCP specification for more information](https://modelcontextprotocol.io/specification/2025-06-18/basic#requests). | | `method` | string | yes | The method to be invoked on the MCP server. [See the MCP specification for more information](https://modelcontextprotocol.io/specification/2025-06-18/basic#requests). | | `params` | object | | The parameters to be passed to the method. [See the MCP specification for more information](https://modelcontextprotocol.io/specification/2025-06-18/basic#requests). | Example: List available tools ```json { "jsonrpc": "2.0", "id": 42, "method": "tools/list" } ``` Example: List the open incidents assigned to the current user ```json { "jsonrpc": "2.0", "id": 43, "method": "tools/call", "params": { "name": "list_incidents", "arguments": { "query_model": { "request_scope": "all", "status": [ "triggered", "acknowledged" ], "limit": 10 } } } } ``` ## Response 200 A successful MCP JSON-RPC response. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `jsonrpc` | string | yes | the JSON-RPC version, always '2.0'. Read-only. | | `id` | string | yes | The unique identifier that was passed to the request. Read-only. | | `result` | object | | The result of the method call. Read-only. | Example: List available tools sample response ```json { "jsonrpc": "2.0", "id": 42, "result": { "tools": [ { "$ref": "#/components/examples/ListIncidentsTool" } ] } } ``` Example: List available tools sample response ```json { "jsonrpc": "2.0", "id": 43, "result": { "response": { "properties": { "items": [ { "$ref": "#/components/examples/Incident" } ] } }, "response_summary": { "properties": { "description": "Generate a summary of the response.", "readOnly": true, "title": "Response Summary", "type": "string" } } } } ``` ## Response 400 Invalid request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `jsonrpc` | string | | | | `error` | object | | | | `error.code` | integer | | Error code. | | `error.message` | string | | Error message. | | `error.data` | object | | Additional error details. | | `error.data.details` | string | | Detailed error message. | | `id` | integer | | The unique identifier for the request. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Generic error response from the PagerDuty API ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/abilities/get-ability # Test an ability `GET https://api.pagerduty.com/abilities/{id}` Test whether your account has a given ability. "Abilities" describes your account's capabilities by feature name. For example `"teams"`. An ability may be available to your account based on things like your pricing plan or account state. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#abilities) Scoped OAuth requires: `abilities.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The account has the requested ability. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/abilities/list-abilities # List abilities `GET https://api.pagerduty.com/abilities` List all of your account's abilities, by name. "Abilities" describes your account's capabilities by feature name. For example `"teams"`. An ability may be available to your account based on things like your pricing plan or account state. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#abilities) Scoped OAuth requires: `abilities.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of ability names. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `abilities` | array of string | yes | The set of abilities your account has. | Example: Example Response ```json { "abilities": [ "teams", "read_only_users", "service_support_hours", "urgencies" ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/add-ons/create-addon # Install an Add-on `POST https://api.pagerduty.com/addons` Install an Add-on for your account. Addon's are pieces of functionality that developers can write to insert new functionality into PagerDuty's UI. Given a configuration containing a `src` parameter, that URL will be embedded in an `iframe` on a page that's available to users from a drop-down menu. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#add-ons) Scoped OAuth requires: `addons.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The Add-on to be installed. | Field | Type | Required | Description | |---|---|---|---| | `addon` | object | yes | | | `addon.id` | string | | Read-only. | | `addon.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `addon.type` | string | yes | The type of Add-on. One of: `full_page_addon`, `incident_show_addon`. | | `addon.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `addon.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `addon.name` | string | yes | The name of the Add-on. Max length: 100. | | `addon.src` | string (url) | yes | The source URL to display in a frame in the PagerDuty UI. HTTPS is required. | Example: Request Example ```json { "addon": { "type": "full_page_addon", "name": "Internal Status Page", "src": "https://intranet.example.com/status" } } ``` ## Response 201 The Add-on that was installed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `addon` | object | yes | | | `addon.id` | string | yes | Read-only. | | `addon.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `addon.type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `addon.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `addon.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `addon.src` | string (url) | | The URL source of the Addon. | | `addon.name` | string | | The user entered name of the Addon. | Example: Response Example ```json { "addon": { "id": "PKX7619", "type": "full_page_addon_reference", "summary": "Internal Status Page", "self": "https://api.pagerduty.com/addons/PKX7619", "html_url": null, "name": "Internal Status Page", "src": "https://intranet.example.com/status" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/add-ons/delete-addon # Delete an Add-on `DELETE https://api.pagerduty.com/addons/{id}` Remove an existing Add-on. Addon's are pieces of functionality that developers can write to insert new functionality into PagerDuty's UI. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#add-ons) Scoped OAuth requires: `addons.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Add-on was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/add-ons/get-addon # Get an Add-on `GET https://api.pagerduty.com/addons/{id}` Get details about an existing Add-on. Addon's are pieces of functionality that developers can write to insert new functionality into PagerDuty's UI. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#add-ons) Scoped OAuth requires: `addons.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requested Add-on. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `addon` | object | yes | | | `addon.id` | string | | Read-only. | | `addon.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `addon.type` | string | yes | The type of Add-on. One of: `full_page_addon`, `incident_show_addon`. | | `addon.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `addon.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `addon.name` | string | yes | The name of the Add-on. Max length: 100. | | `addon.src` | string (url) | yes | The source URL to display in a frame in the PagerDuty UI. HTTPS is required. | Example: Example Response ```json { "addon": { "id": "PKX7F81", "type": "incident_show_addon", "name": "Service Runbook", "src": "https://intranet.example.com/runbook.html", "services": [ { "id": "PIJ90N7", "type": "service", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/add-ons/list-addon # List installed Add-ons `GET https://api.pagerduty.com/addons` List all of the Add-ons installed on your account. Addon's are pieces of functionality that developers can write to insert new functionality into PagerDuty's UI. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#add-ons) Scoped OAuth requires: `addons.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `services`. Items must be unique. | | `service_ids[]` | array of string | | Filters the results, showing only Add-ons for the given services. Items must be unique. | | `filter` | string | | Filters the results, showing only Add-ons of the given type. One of: `full_page_addon`, `incident_show_addon`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of installed Add-ons. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `addons` | array of object | yes | | | `addons[].id` | string | yes | Read-only. | | `addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `addons[].src` | string (url) | | The URL source of the Addon. | | `addons[].name` | string | | The user entered name of the Addon. | Example: Example Response ```json { "addons": [ { "id": "PKX7619", "type": "full_page_addon_reference", "summary": "Internal Status Page", "self": "https://api.pagerduty.com/addons/PKX7619", "html_url": null, "name": "Internal Status Page", "src": "https://intranet.example.com/status" } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/add-ons/update-addon # Update an Add-on `PUT https://api.pagerduty.com/addons/{id}` Update an existing Add-on. Addon's are pieces of functionality that developers can write to insert new functionality into PagerDuty's UI. Given a configuration containing a `src` parameter, that URL will be embedded in an `iframe` on a page that's available to users from a drop-down menu. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#add-ons) Scoped OAuth requires: `addons.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The Add-on to be updated. | Field | Type | Required | Description | |---|---|---|---| | `addon` | object | yes | | | `addon.id` | string | | Read-only. | | `addon.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `addon.type` | string | yes | The type of Add-on. One of: `full_page_addon`, `incident_show_addon`. | | `addon.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `addon.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `addon.name` | string | yes | The name of the Add-on. Max length: 100. | | `addon.src` | string (url) | yes | The source URL to display in a frame in the PagerDuty UI. HTTPS is required. | Example: Request Example ```json { "addon": { "type": "full_page_addon", "name": "Internal Status Page", "src": "https://intranet.example.com/status" } } ``` ## Response 200 The Add-on that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `addon` | object | yes | Same fields as `addon` above. | Example: Response Example ```json { "addon": { "id": "PKX7F81", "type": "incident_show_addon", "name": "Service Runbook", "src": "https://intranet.example.com/runbook.html", "services": [ { "id": "PIJ90N7", "type": "service", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/delete-alert-grouping-setting # Delete an Alert Grouping Setting `DELETE https://api.pagerduty.com/alert_grouping_settings/{id}` Delete an existing Alert Grouping Setting. The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Alert Grouping Setting was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/get-alert-grouping-setting # Get an Alert Grouping Setting `GET https://api.pagerduty.com/alert_grouping_settings/{id}` Get an existing Alert Grouping Setting. The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Alert Grouping Setting. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_setting` | object | yes | Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans. | | `alert_grouping_setting.id` | string | | Read-only. | | `alert_grouping_setting.name` | string \| null | | An optional short-form string that provides succinct information about an AlertGroupingSetting object suitable for primary labeling of the entity. It is not intended to be an identifier. | | `alert_grouping_setting.description` | string \| null | | An optional description in string that provides more information about an AlertGroupingSetting object. | | `alert_grouping_setting.type` | string | | One of: `content_based`, `content_based_intelligent`, `intelligent`, `time`. | | `alert_grouping_setting.config` | one of: object \| object \| object \| object | | | | `alert_grouping_setting.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.aggregate` | string | | (Content and Intelligent Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content and Intelligent Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content and Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content and Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.timeout` | integer | | (Time Grouping) The duration in seconds within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 60. Maximum: 86400. | | `alert_grouping_setting.config.time_window` | integer | | (Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.iag_fields` | array of string | | (Intelligent Grouping) An array of strings which represent the iag fields with which to intelligently group against. Default: `["summary"]`. | | `alert_grouping_setting.services` | array of object | | The array of one or many Services with just ServiceID/name that the AlertGroupingSetting applies to. Type of content_based_intelligent allows for only one service in the array. | | `alert_grouping_setting.services[].id` | string | yes | Read-only. | | `alert_grouping_setting.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert_grouping_setting.services[].type` | string | yes | One of: `service_reference`. | | `alert_grouping_setting.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert_grouping_setting.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert_grouping_setting.created_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting got created at. Read-only. | | `alert_grouping_setting.updated_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting last got updated at. Read-only. | Example: Response Example ```json { "alert_grouping_setting": { "id": "PZC4OM1", "name": "Example of Alert Grouping Setting", "description": "This Alert Grouping Setting is an example", "type": "content_based", "config": { "time_window": 900, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A", "name": "Payment Service" }, { "id": "PA15YRT", "name": "Checkout Service" } ], "created_at": "2022-12-13T19:55:01.171Z", "updated_at": "2023-08-24T18:29:35.630Z" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/list-alert-grouping-settings # List alert grouping settings `GET https://api.pagerduty.com/alert_grouping_settings` List all of your alert grouping settings including both single service settings and global content based settings. The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `after` | string | | Cursor to retrieve next page; only present if next page exists. | | `before` | string | | Cursor to retrieve previous page; only present if not on first page. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `limit` | integer | | The number of results per page. | | `service_ids[]` | array of string | | An array of service IDs. Only results related to these services will be returned. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of alert grouping settings. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_settings` | array of object | yes | The list of alert grouping settings your account has. | | `alert_grouping_settings[].id` | string | | Read-only. | | `alert_grouping_settings[].name` | string \| null | | An optional short-form string that provides succinct information about an AlertGroupingSetting object suitable for primary labeling of the entity. It is not intended to be an identifier. | | `alert_grouping_settings[].description` | string \| null | | An optional description in string that provides more information about an AlertGroupingSetting object. | | `alert_grouping_settings[].type` | string | | One of: `content_based`, `content_based_intelligent`, `intelligent`, `time`. | | `alert_grouping_settings[].config` | one of: object \| object \| object \| object | | | | `alert_grouping_settings[].config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_settings[].config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_settings[].config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `alert_grouping_settings[].config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_settings[].config.aggregate` | string | | (Content and Intelligent Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_settings[].config.fields` | array of string | | (Content and Intelligent Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_settings[].config.time_window` | integer | | (Content and Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_settings[].config.recommended_time_window` | integer | | (Content and Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_settings[].config.timeout` | integer | | (Time Grouping) The duration in seconds within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 60. Maximum: 86400. | | `alert_grouping_settings[].config.time_window` | integer | | (Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_settings[].config.recommended_time_window` | integer | | (Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_settings[].config.iag_fields` | array of string | | (Intelligent Grouping) An array of strings which represent the iag fields with which to intelligently group against. Default: `["summary"]`. | | `alert_grouping_settings[].services` | array of object | | The array of one or many Services with just ServiceID/name that the AlertGroupingSetting applies to. Type of content_based_intelligent allows for only one service in the array. | | `alert_grouping_settings[].services[].id` | string | yes | Read-only. | | `alert_grouping_settings[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert_grouping_settings[].services[].type` | string | yes | One of: `service_reference`. | | `alert_grouping_settings[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert_grouping_settings[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert_grouping_settings[].created_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting got created at. Read-only. | | `alert_grouping_settings[].updated_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting last got updated at. Read-only. | Example: Response Example ```json { "alert_grouping_settings": [ { "id": "PJWA06X", "name": "Example of Alert Grouping Setting", "description": "This is an example of list of Alert Grouping Settings", "type": "content_based", "config": { "time_window": 86400, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A", "name": "Payment Service" }, { "id": "PA15YRT", "name": "Checkout Service" } ], "created_at": "2022-12-13T19:55:01.171Z", "updated_at": "2023-08-24T18:29:35.630Z" } ], "after": "g3QAAAACZAACaWRhB2QAC2luc2VydGVkX2F0dAAAAAlkAApfX3N0cnVjdF9fZAAURWxpeGlyLk5haXZlRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhA2QABGhvdXJhFGQAC21pY3Jvc2Vjb25kaAJiAAL81WEGZAAGbWludXRlYR5kAAVtb250aGEIZAAGc2Vjb25kYR5kAAR5ZWFyYgAAB", "before": "g3QAAAACZAACaWRhCGQAC2luc2VydGVkX2F0dAAAAAlkAApfX3N0cnVjdF9fZAAURWxpeGlyLk5haXZlRGF0ZVRpbWVkAAhjYWxlbmRhcmQAE0VsaXhpci5DYWxlbmRhci5JU09kAANkYXlhA2QABGhvdXJhFGQAC21pY3Jvc2Vjb25kaAJiAANYzWEGZAAGbWludXRlYR5kAAVtb250aGEIZAAGc2Vjb25kYR5kAAR5ZWFyYgAAB", "limit": 25, "total": null } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings # Create an Alert Grouping Setting `POST https://api.pagerduty.com/alert_grouping_settings` Create a new Alert Grouping Setting. The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts. This endpoint will be used to create an instance of AlertGroupingSettings for either one service or many services that are in the alert group setting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_setting` | object | yes | Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans. | | `alert_grouping_setting.id` | string | | Read-only. | | `alert_grouping_setting.name` | string \| null | | An optional short-form string that provides succinct information about an AlertGroupingSetting object suitable for primary labeling of the entity. It is not intended to be an identifier. | | `alert_grouping_setting.description` | string \| null | | An optional description in string that provides more information about an AlertGroupingSetting object. | | `alert_grouping_setting.type` | string | | One of: `content_based`, `content_based_intelligent`, `intelligent`, `time`. | | `alert_grouping_setting.config` | one of: object \| object \| object \| object | | | | `alert_grouping_setting.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.aggregate` | string | | (Content and Intelligent Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content and Intelligent Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content and Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content and Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.timeout` | integer | | (Time Grouping) The duration in seconds within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 60. Maximum: 86400. | | `alert_grouping_setting.config.time_window` | integer | | (Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.iag_fields` | array of string | | (Intelligent Grouping) An array of strings which represent the iag fields with which to intelligently group against. Default: `["summary"]`. | | `alert_grouping_setting.services` | array of object | | The array of one or many Services with just ServiceID/name that the AlertGroupingSetting applies to. Type of content_based_intelligent allows for only one service in the array. | | `alert_grouping_setting.services[].id` | string | yes | Read-only. | | `alert_grouping_setting.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert_grouping_setting.services[].type` | string | yes | One of: `service_reference`. | | `alert_grouping_setting.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert_grouping_setting.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert_grouping_setting.created_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting got created at. Read-only. | | `alert_grouping_setting.updated_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting last got updated at. Read-only. | Example: Request Example ```json { "alert_grouping_setting": { "id": "PZC4OM1", "name": "Example of Alert Grouping Setting", "description": "This Alert Grouping Setting is an example", "type": "content_based", "config": { "time_window": 900, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A" }, { "id": "PA15YRT" } ] } } ``` ## Response 201 The new Alert Grouping Setting. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_setting` | object | yes | Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans. Same fields as `alert_grouping_setting` above. | Example: Response Example ```json { "alert_grouping_setting": { "id": "PZC4OM1", "name": "Example of Alert Grouping Setting", "description": "This Alert Grouping Setting is an example", "type": "content_based", "config": { "time_window": 900, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A", "name": "Payment Service" }, { "id": "PA15YRT", "name": "Checkout Service" } ], "created_at": "2022-12-13T19:55:01.171Z", "updated_at": "2023-08-24T18:29:35.630Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/put-alert-grouping-setting # Update an Alert Grouping Setting `PUT https://api.pagerduty.com/alert_grouping_settings/{id}` Update an Alert Grouping Setting. The settings part of Alert Grouper service allows us to create Alert Grouping Settings and configs that are required to be used during grouping of the alerts. if `services` are not provided in the request, then the existing services will not be removed from the setting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_setting` | object | yes | Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans. | | `alert_grouping_setting.id` | string | | Read-only. | | `alert_grouping_setting.name` | string \| null | | An optional short-form string that provides succinct information about an AlertGroupingSetting object suitable for primary labeling of the entity. It is not intended to be an identifier. | | `alert_grouping_setting.description` | string \| null | | An optional description in string that provides more information about an AlertGroupingSetting object. | | `alert_grouping_setting.type` | string | | One of: `content_based`, `content_based_intelligent`, `intelligent`, `time`. | | `alert_grouping_setting.config` | one of: object \| object \| object \| object | | | | `alert_grouping_setting.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.aggregate` | string | | (Content and Intelligent Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `alert_grouping_setting.config.fields` | array of string | | (Content and Intelligent Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `alert_grouping_setting.config.time_window` | integer | | (Content and Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Content and Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.timeout` | integer | | (Time Grouping) The duration in seconds within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 60. Maximum: 86400. | | `alert_grouping_setting.config.time_window` | integer | | (Intelligent Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600. Minimum: 300. Maximum: 3600. | | `alert_grouping_setting.config.recommended_time_window` | integer | | (Intelligent Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `alert_grouping_setting.config.iag_fields` | array of string | | (Intelligent Grouping) An array of strings which represent the iag fields with which to intelligently group against. Default: `["summary"]`. | | `alert_grouping_setting.services` | array of object | | The array of one or many Services with just ServiceID/name that the AlertGroupingSetting applies to. Type of content_based_intelligent allows for only one service in the array. | | `alert_grouping_setting.services[].id` | string | yes | Read-only. | | `alert_grouping_setting.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert_grouping_setting.services[].type` | string | yes | One of: `service_reference`. | | `alert_grouping_setting.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert_grouping_setting.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert_grouping_setting.created_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting got created at. Read-only. | | `alert_grouping_setting.updated_at` | string (date-time) | | The ISO8601 date/time an AlertGroupingSetting last got updated at. Read-only. | Example: Request Example ```json { "alert_grouping_setting": { "id": "PZC4OM1", "name": "Example of Alert Grouping Setting", "description": "This Alert Grouping Setting is an example", "type": "content_based", "config": { "time_window": 900, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A" }, { "id": "PA15YRT" } ] } } ``` ## Response 200 The updated Alert Grouping Setting. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert_grouping_setting` | object | yes | Defines how alerts will be automatically grouped into incidents based on the configurations defined. Note that the Alert Grouping Setting features are available only on certain plans. Same fields as `alert_grouping_setting` above. | Example: Response Example ```json { "alert_grouping_setting": { "id": "PZC4OM1", "name": "Example of Alert Grouping Setting", "description": "This Alert Grouping Setting is an example", "type": "content_based", "config": { "time_window": 900, "aggregate": "all", "fields": [ "summary", "component", "custom_details.host", "custom_details.field1.field2" ] }, "services": [ { "id": "P0KJZ0A", "name": "Payment Service" }, { "id": "PA15YRT", "name": "Checkout Service" } ], "created_at": "2022-12-13T19:55:01.171Z", "updated_at": "2023-08-24T18:29:35.630Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-incident-responses-by-id # Get raw responses from a single incident `GET https://api.pagerduty.com/analytics/raw/incidents/{id}/responses` Provides enriched responder data for a single incident. Example metrics include Time to Respond, Responder Type, and Response Status. See metric definitions below. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Number of results to include in each batch. Limits between 1 to 1000 are accepted. Greater than 0. Maximum: 1000. | | `order` | string | | The order in which to display the results; asc for ascending, desc for descending. Defaults to `desc`. One of: `asc`, `desc`. | | `order_by` | string | | The column to use for ordering the results. One of: `requested_at`. | | `time_zone` | string | | The time zone to use for the results. | Example: Example Request ```json { "limit": 20, "order": "desc", "order_by": "requested_at", "time_zone": "America/Los_Angeles" } ``` ## Response 200 ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_id` | string | | The Incident ID passed into the request. | | `limit` | integer | | Number of results to include in the batch. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. One of: `requested_at`. | | `time_zone` | string | | The time zone that the results are in. | | `responses` | array of object | | | | `responses[].responder_name` | string | | Name of the user associated with the Incident Response. | | `responses[].responder_id` | string | | ID of the user associated with the Incident Response. | | `responses[].response_status` | string | | Status of the user's interaction with the Incident notification. One of: `joined`, `pending`, `declined`. | | `responses[].responder_type` | string | | Type of responder, where `assigned` means the user was added to the Incident via Assignment at Incident creation, `reassigned` means the user was added to the Incident via Reassignment, `escalated` means the user was added via Escalation, and `added_responder` means the user was added via Responder Reqeuest. One of: `assigned`, `reassigned`, `escalated`, `added_responder`. | | `responses[].requested_at` | string | | Timestamp of when the user was requested. | | `responses[].responded_at` | string | | Timestamp of when the user responded to the request. | | `responses[].time_to_respond_seconds` | integer | | Measures the time it took for the user to respond to the Incident request. In other words, `responded_at - requested_at`. | Example: Example Response ```json { "incident_id": "PJASD33", "limit": 100, "order": "asc", "order_by": "requested_at", "time_zone": "Etc/UTC", "responses": { "requested_at": "2024-01-05T10:15:00", "responded_at": "2024-01-05T10:18:00", "responder_id": "PXPGF42", "responder_name": "Earline Greenholt", "responder_type": "added_responder", "response_status": "accepted", "time_to_respond_seconds": 180 } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-incidents # Get raw data - multiple incidents `POST https://api.pagerduty.com/analytics/raw/incidents` Provides enriched incident data and metrics for multiple incidents. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#incidents-list). > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Filters the result, only show incidents that match the conditions passed in the filter. | | `filters.created_at_start` | string | | Filters the result, showing only the incidents where the creation timestamp is greater than or equal to the filter value. | | `filters.created_at_end` | string | | Filters the result, showing only the incidents where the creation timestamp is less than the filter value. | | `filters.updated_after` | string | | Filters the result, showing only incidents where the updated_at value is greater than the filter value. | | `filters.urgency` | string | | Filters the result, showing only the incidents where urgency matches the filter value. | | `filters.major` | boolean | | An incident is classified as a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) if it has one of the two highest priorities, or if multiple responders are added and acknowledge the incident. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents that are assigned to a member of these teams will be returned. Account must have the teams ability to use this parameter. | | `filters.service_ids` | array of string | | An array of service IDs. Only results related to these services will be returned. | | `filters.priority_ids` | array of string | | The priority_ids filter applied to the results. | | `filters.priority_names` | array of string | | The priority_names filter applied to the results. | | `filters.incident_type_ids` | array of string | | Filter incidents by specific incident type IDs. Only incidents matching the given IDs will be returned. | | `starting_after` | string | | A cursor to indicate the reference point that the results should follow. | | `ending_before` | string | | A cursor to indicate the reference point that the results should precede. | | `order` | string | | The order the results; asc for ascending, desc for descending. Defaults to 'desc'. One of: `asc`, `desc`. | | `order_by` | string | | The column to use for ordering the results. Defaults to 'created_at'. One of: `created_at`, `seconds_to_resolve`. | | `limit` | integer | | Number of results to include in each batch. Limits between 1 to 1000 are accepted. Greater than 0. Maximum: 1000. | | `time_zone` | string | | The time zone to use for the results. | Example: Example Request ```json { "filters": { "created_at_start": "2024-01-01T00:00:00-05:00", "created_at_end": "2024-01-31T00:00:00-05:00", "updated_after": "2024-05-01T00:00:00-05:00", "urgency": "high", "major": true, "team_ids": [ "PGVXG6U", "PNVU4U4" ], "service_ids": [ "PQVUB8D", "PU2D9X3" ], "priority_names": [ "P1", "P2" ], "incident_type_ids": [ "PIJ90N7", "PKL73Z2" ] }, "limit": 20, "order": "desc", "order_by": "created_at", "time_zone": "Etc/UTC" } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `first` | string | yes | Cursor to identify the first object in the response. | | `last` | string | yes | Cursor to identify the last object in the response. | | `limit` | integer | yes | Number of results to include in the batch. | | `more` | boolean | yes | Indicates if there are more resources available than were returned. | | `order` | string | yes | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | yes | The column that was used for ordering the results. One of: `created_at`, `seconds_to_resolve`, `updated_at`. | | `filters` | object | | A collection of filters that were applied to the results. | | `filters.created_at_start` | string | | The lower boundary for the created_at range filter applied to the results. | | `filters.created_at_end` | string | | The upper boundary for the created_at range filter applied to the results. | | `filters.urgency` | string | | The urgency filter applied to the results. One of: `high`, `low`. | | `filters.major` | boolean | | The [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) filter applied to the results. | | `filters.team_ids` | array of string | | The team_ids filter applied to the results. | | `filters.service_ids` | array of string | | The service_ids filter applied to the results. | | `filters.priority_ids` | array of string | | The priority_ids filter applied to the results. Max items: 5. | | `filters.priority_names` | array of string | | The priority_names filter applied to the results. Max items: 5. | | `filters.incident_type_ids` | array of string | | The incident_type_ids filter applied to the results. | | `time_zone` | string | yes | The time zone that the results are in. | | `data` | array of object | yes | | | `data[].acknowledged_user_ids` | array of string | | The IDs of the users who acknowledged the incident. | | `data[].acknowledged_user_names` | array of string | | The names of the users who acknowledged the incident. | | `data[].acknowledgement_count` | integer | | Total count of acknowledgements in the incident. | | `data[].active_user_count` | integer | | Total number of responders who either acknowledged the incident or accepted a responder request. | | `data[].assigned_user_ids` | array of string | | The IDs of the users who were assigned the incident. | | `data[].assigned_user_names` | array of string | | The names of the users who were assigned the incident. | | `data[].assignment_count` | integer | | Total count of instances where responders were assigned an incident (including through reassignment or escalation). | | `data[].auto_resolved` | boolean | | Whether or not the incident resolved automatically, either via an integration or [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].created_at` | string | | Timestamp of when the incident was created. | | `data[].updated_at` | string | | Timestamp of when the incident was last updated by the analytics process. Does not match the updated_at for an incident returned by the standard REST api incidents endpoint. | | `data[].description` | string | | The incident description. | | `data[].engaged_seconds` | integer | | Total engaged time across all responders for this incident. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].engaged_user_count` | integer | | Total number of users who engaged (acknowledged, accepted responder request) in the incident. | | `data[].escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].escalation_policy_id` | string | | ID of the escalation policy the incident was assigned to. | | `data[].escalation_policy_name` | string | | Name of the escalation policy the incident was assigned to. | | `data[].id` | string | | Incident ID. | | `data[].incident_number` | integer | | The PagerDuty incident number. | | `data[].incident_type_id` | string | | ID of the Incident Type. | | `data[].incident_type_name` | string | | The name of the Incident Type. | | `data[].joined_user_ids` | array of string | | The IDs of the users who either acknowledged the incident or accepted a responder request. | | `data[].joined_user_names` | array of string | | The names of the users who either acknowledged the incident or accepted a responder request. | | `data[].major` | boolean | | An incident is classified as a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) if it has one of the two highest priorities, or if multiple responders are added and acknowledge the incident. | | `data[].manual_escalation_count` | integer | | Total count of manual escalations in the incident. | | `data[].off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].priority_id` | string \| null | | ID of the incident's priority level. | | `data[].priority_name` | string \| null | | The user-provided short name of the priority. | | `data[].priority_order` | integer \| null | | The numerical value used to sort priorities. Higher values are higher priority. | | `data[].reassignment_count` | integer | | Total count of reassignments in the incident. | | `data[].resolved_at` | string | | Timestamp of when the incident was resolved. | | `data[].resolved_by_user_id` | string | | ID of the user who resolved the incident. | | `data[].resolved_by_user_name` | string | | Name of the user who resolved the incident. | | `data[].seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].seconds_to_first_ack` | integer | | Time between the start of an incident, and the first responder to acknowledge. | | `data[].seconds_to_mobilize` | integer | | Time between the start of an incident, and the last additional responder to acknowledge. If an incident has one or no responders, the value will be null. | | `data[].seconds_to_resolve` | integer | | Time from when an incident was triggered until it was resolved. | | `data[].service_id` | string | | ID of the service that the incident triggered on. | | `data[].service_name` | string | | Name of the service that the incident triggered on. | | `data[].sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `data[].snoozed_seconds` | integer | | Total seconds the incident has been snoozed for. | | `data[].status` | string | | The incident status. Can be one of `triggered`, `acknowledged`, or `resolved`. | | `data[].team_id` | string \| null | | ID of the team the incident was assigned to. | | `data[].team_name` | string \| null | | Name of the team the incident was assigned to. | | `data[].timeout_escalation_count` | integer | | Total count of timeout escalations in the incident. | | `data[].total_interruptions` | integer | | Total number of unique interruptions in the incident. | | `data[].total_notifications` | integer | | Total number of notifications sent for the incident. | | `data[].urgency` | string | | Notification level. | | `data[].user_defined_effort_seconds` | integer \| null | | The total response effort in seconds, [as defined by the user](https://support.pagerduty.com/docs/editing-incidents#edit-incident-duration). | Example: Example Response ```json { "data": [ { "acknowledged_user_ids": [ "PRJ4208" ], "acknowledged_user_names": [ "John Smith" ], "acknowledgement_count": 1, "active_user_count": 3, "assigned_user_ids": [ "PRJ4208", "PA02301" ], "assigned_user_names": [ "John Smith", "Jane Doe" ], "assignment_count": 2, "auto_resolved": false, "business_hour_interruptions": 5, "created_at": "2023-05-31T10:05:00", "updated_at": "2023-06-04T00:00:00", "description": "The server is on fire!", "engaged_seconds": 3510, "engaged_user_count": 10, "escalation_count": 1, "escalation_policy_id": "PDESCP1", "escalation_policy_name": "Escalation Policy 1", "id": "PYC0H08", "incident_number": 928, "incident_type_id": "PIJ90N7", "incident_type_name": "incident_default", "joined_user_ids": [ "PRJ4208", "PA02301", "P40D0J1" ], "joined_user_names": [ "John Smith", "Jane Doe", "Wanda Evans" ], "major": false, "manual_escalation_count": 0, "off_hour_interruptions": 4, "priority_id": null, "priority_name": null, "priority_order": null, "reassignment_count": 0, "resolved_at": "2023-05-31T10:15:00", "resolved_by_user_id": "PRJ4208", "resolved_by_user_name": "John Smith", "seconds_to_engage": 70, "seconds_to_first_ack": 5, "seconds_to_mobilize": 19, "seconds_to_resolve": 3305, "service_id": "PPSCXAN", "service_name": "Engineering", "sleep_hour_interruptions": 3, "snoozed_seconds": 604, "status": "resolved", "team_id": null, "team_name": null, "timeout_escalation_count": 0, "total_interruptions\"": null, "total_notifications": 2, "urgency": "low", "user_defined_effort_seconds": null }, { "acknowledged_user_ids": [ "PMT4102" ], "acknowledged_user_names": [ "Sally Styles" ], "acknowledgement_count": 1, "active_user_count": 1, "assigned_user_ids": [ "PMT4102" ], "assigned_user_names": [ "Sally Styles" ], "assignment_count": 1, "business_hour_interruptions": 2, "created_at": "2023-05-31T10:00:00", "updated_at": "2023-06-04T00:00:00", "description": "Reply on social media", "engaged_seconds": 521, "engaged_user_count": 6, "escalation_count": 1, "escalation_policy_id": "PDESCP1", "escalation_policy_name": "Escalation Policy 1", "id": "PCOOHCY", "incident_number": 929, "incident_type_id": "PIJ90N7", "incident_type_name": "incident_default", "joined_user_ids": [ "PMT4102" ], "joined_user_names": [ "Sally Styles" ], "major": false, "manual_escalation_count": 0, "off_hour_interruptions": 3, "priority_id": "POTCOTX", "priority_name": "SEV-2", "priority_order": null, "reassignment_count": 0, "resolved_at": "2023-05-30T10:00:05", "resolved_by_user_id": "PMT4102", "resolved_by_user_name": "Sally Styles", "seconds_to_engage": 24, "seconds_to_first_ack": 48, "seconds_to_mobilize": 122, "seconds_to_resolve": 2029, "service_id": "PPSCXAN", "service_name": "Social media tracking", "sleep_hour_interruptions": 1, "snoozed_seconds": 698, "status": "resolved", "team_id": null, "team_name": "Marketing", "timeout_escalation_count": 0, "total_interruptions\"": null, "total_notifications": 2, "urgency": "low", "user_defined_effort_seconds": null } ], "ending_before": null, "filters": {}, "first": "PYC0H08", "last": "PCOOHCY", "limit": 10, "more": true, "order": "desc", "order_by": "created_at", "starting_after": null, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-incidents-by-id # Get raw data - single incident `GET https://api.pagerduty.com/analytics/raw/incidents/{id}` Provides enriched incident data and metrics for a single incident. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#incidents-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `acknowledged_user_ids` | array of string | | The IDs of the users who acknowledged the incident. | | `acknowledged_user_names` | array of string | | The names of the users who acknowledged the incident. | | `acknowledgement_count` | integer | | Total count of acknowledgements in the incident. | | `active_user_count` | integer | | Total number of responders who either acknowledged the incident or accepted a responder request. | | `assigned_user_ids` | array of string | | The IDs of the users who were assigned the incident. | | `assigned_user_names` | array of string | | The names of the users who were assigned the incident. | | `assignment_count` | integer | | Total count of instances where responders were assigned an incident (including through reassignment or escalation). | | `auto_resolved` | boolean | | Whether or not the incident resolved automatically, either via an integration or [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `created_at` | string | | Timestamp of when the incident was created. | | `updated_at` | string | | Timestamp of when the incident was last updated by the analytics process. Does not match the updated_at for an incident returned by the standard REST api incidents endpoint. | | `description` | string | | The incident description. | | `engaged_seconds` | integer | | Total engaged time across all responders for this incident. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `engaged_user_count` | integer | | Total number of users who engaged (acknowledged, accepted responder request) in the incident. | | `escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `escalation_policy_id` | string | | ID of the escalation policy the incident was assigned to. | | `escalation_policy_name` | string | | Name of the escalation policy the incident was assigned to. | | `id` | string | | Incident ID. | | `incident_number` | integer | | The PagerDuty incident number. | | `incident_type_id` | string | | ID of the Incident Type. | | `incident_type_name` | string | | The name of the Incident Type. | | `joined_user_ids` | array of string | | The IDs of the users who either acknowledged the incident or accepted a responder request. | | `joined_user_names` | array of string | | The names of the users who either acknowledged the incident or accepted a responder request. | | `major` | boolean | | An incident is classified as a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) if it has one of the two highest priorities, or if multiple responders are added and acknowledge the incident. | | `manual_escalation_count` | integer | | Total count of manual escalations in the incident. | | `off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `priority_id` | string \| null | | ID of the incident's priority level. | | `priority_name` | string \| null | | The user-provided short name of the priority. | | `priority_order` | integer \| null | | The numerical value used to sort priorities. Higher values are higher priority. | | `reassignment_count` | integer | | Total count of reassignments in the incident. | | `resolved_at` | string | | Timestamp of when the incident was resolved. | | `resolved_by_user_id` | string | | ID of the user who resolved the incident. | | `resolved_by_user_name` | string | | Name of the user who resolved the incident. | | `seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `seconds_to_first_ack` | integer | | Time between the start of an incident, and the first responder to acknowledge. | | `seconds_to_mobilize` | integer | | Time between the start of an incident, and the last additional responder to acknowledge. If an incident has one or no responders, the value will be null. | | `seconds_to_resolve` | integer | | Time from when an incident was triggered until it was resolved. | | `service_id` | string | | ID of the service that the incident triggered on. | | `service_name` | string | | Name of the service that the incident triggered on. | | `sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `snoozed_seconds` | integer | | Total seconds the incident has been snoozed for. | | `status` | string | | The incident status. Can be one of `triggered`, `acknowledged`, or `resolved`. | | `team_id` | string \| null | | ID of the team the incident was assigned to. | | `team_name` | string \| null | | Name of the team the incident was assigned to. | | `timeout_escalation_count` | integer | | Total count of timeout escalations in the incident. | | `total_interruptions` | integer | | Total number of unique interruptions in the incident. | | `total_notifications` | integer | | Total number of notifications sent for the incident. | | `urgency` | string | | Notification level. | | `user_defined_effort_seconds` | integer \| null | | The total response effort in seconds, [as defined by the user](https://support.pagerduty.com/docs/editing-incidents#edit-incident-duration). | Example: Example Response ```json { "time_zone": "Etc/UTC", "data": { "acknowledged_user_ids": [ "PRJ4208" ], "acknowledged_user_names": [ "Santos Dicera" ], "acknowledgement_count": 1, "active_user_count": 2, "assigned_user_ids": [ "PRJ4208", "PA02301" ], "assigned_user_names": [ "Santos Dicera", "Jane Doe" ], "assignment_count": 2, "auto_resolved": false, "business_hour_interruptions": 0, "created_at": "2024-01-01T21:00:00Z", "updated_at": "2024-06-01T00:00:00Z", "description": "The server is on fire!", "engaged_seconds": 75, "engaged_user_count": 2, "escalation_count": 0, "escalation_policy_id": "PCI3U5T", "escalation_policy_name": "Sputnik", "id": "PJASD33", "incident_number": 924, "incident_type_id": "PIJ90N7", "incident_type_name": "incident_default", "joined_user_ids": [ "PRJ4208", "PA02301" ], "joined_user_names": [ "Santos Dicera", "Jane Doe" ], "major": true, "manual_escalation_count": 0, "off_hour_interruptions": 2, "priority_id": "PZOZQXA", "priority_name": "SEV-1", "priority_order": 67108864, "reassignment_count": 0, "resolved_at": "2024-01-02T21:01:00Z", "resolved_by_user_id": "PRJ4208", "resolved_by_user_name": "Santos Dicera", "seconds_to_engage": 30, "seconds_to_first_ack": 15, "seconds_to_mobilize": 15, "seconds_to_resolve": 60, "service_id": "PAQTPI2", "service_name": "Engineering", "sleep_hour_interruptions": 0, "snoozed_seconds": 0, "status": "resolved", "team_id": "PNVU4UR", "team_name": "Engineering team 7", "timeout_escalation_count": 0, "total_interruptions": null, "total_notifications": 2, "urgency": "high", "user_defined_effort_seconds": null } } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-all # Get aggregated incident data `POST https://api.pagerduty.com/analytics/metrics/incidents/all` Provides aggregated enriched metrics for incidents. The provided metrics are aggregated by day, week, month using the aggregate_unit parameter, or for the entire period if no aggregate_unit is provided. > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2024-01-01T00:00:00-05:00", "created_at_end": "2024-01-31T00:00:00-05:00", "urgency": "high", "major": true, "team_ids": [ "PGVXG6U", "PNVU4U4" ], "service_ids": [ "PQVUB8D", "PU2D9X3" ] }, "aggregate_unit": "day", "time_zone": "Etc/UTC" } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].p50_seconds_to_first_ack` | integer | | Median time between the start of an incident, and the first responder to acknowledge. | | `data[].p50_seconds_to_resolve` | integer | | Median time from when an incident was triggered until it was resolved. | | `data[].p75_seconds_to_first_ack` | integer | | 75th percentile for the time between the start of an incident, and the first responder to acknowledge. | | `data[].p75_seconds_to_resolve` | integer | | 75th percentile for the time when an incident was triggered until it was resolved. | | `data[].p90_seconds_to_first_ack` | integer | | 90th percentile for the time between the start of an incident, and the first responder to acknowledge. | | `data[].p90_seconds_to_resolve` | integer | | 90th percentile for the time when an incident was triggered until it was resolved. | | `data[].p95_seconds_to_first_ack` | integer | | 95th percentile for the time between the start of an incident, and the first responder to acknowledge. | | `data[].p95_seconds_to_resolve` | integer | | 95th percentile for the time when an incident was triggered until it was resolved. | | `data[].range_start` | string | | Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request. | | `data[].service_id` | string | | ID of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].service_name` | string | | Name of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].team_id` | string | | ID of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours. Sleep hours: 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Only included when aggregating by team, escalation policy, service, or all services. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "aggregate_unit": "day", "data": [ { "mean_assignment_count": 1, "mean_engaged_seconds": 366, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 81, "mean_seconds_to_first_ack": 63, "mean_seconds_to_mobilize": 41, "mean_seconds_to_resolve": 380, "mean_user_defined_engaged_seconds": 366, "range_start": "2024-01-01T00:00:00", "total_business_hour_interruptions": 81, "total_engaged_seconds": 3591, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 0, "total_incidents_auto_resolved": 0, "total_incidents_manual_escalated": 0, "total_incidents_reassigned": 0, "total_incidents_timeout_escalated": 0, "total_interruptions": 2, "total_notifications": 2, "total_off_hour_interruptions": 20, "total_sleep_hour_interruptions": 21, "total_snoozed_seconds": 78, "total_user_defined_engaged_seconds": 3591 } ], "filters": { "create_range_start": "2024-01-01T00:00:00Z", "create_range_end": "2024-02-01T00:00:00Z", "urgency": "high", "major": true, "team_ids": [ "PGVXG6U", "PNVU4U4" ], "service_ids": [ "PQVUB8D", "PU2D9X3" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-escalation-policy # Get aggregated escalation policy data `POST https://api.pagerduty.com/analytics/metrics/incidents/escalation_policies` Provides aggregated metrics for incidents aggregated into units of time by escalation policy. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#escalation-policy-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-10T00:00:00-07:00", "created_at_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "major": true, "escalation_policy_ids": [ "PDESCP1", "PDESCP2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for escalation policies that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].distinct_responder_count` | integer | | Distinct count of responders who engaged in incidents on the escalation policy. | | `data[].escalation_policy_id` | string | | ID of the escalation policy the incident was last assigned to. Not included when aggregating by all. | | `data[].escalation_policy_name` | string | | Name of the escalation policy the incident was last assigned to. Not included when aggregating by all. | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range that the metrics were calculated for. Only included when an aggregate unit is specified in the request. | | `data[].team_id` | string | | ID of the team the incident was assigned to. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team the incident was assigned to. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Not included when aggregating by all. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "data": [ { "distinct_responder_count": 1, "escalation_policy_id": "PDESCP1", "escalation_policy_name": "Escalation Policy 1", "mean_assignment_count": 1, "mean_engaged_seconds": 81, "mean_engaged_user_count": 63, "mean_seconds_to_engage": 41, "mean_seconds_to_first_ack": 380, "mean_seconds_to_mobilize": 81, "mean_seconds_to_resolve": 3591, "mean_user_defined_engaged_seconds": 81, "team_id": "PDTEAM1", "team_name": "Team 1", "total_business_hour_interruptions": 5, "total_engaged_seconds": 124, "total_escalation_count": 20, "total_incident_count": 21, "total_incidents_acknowledged": 78, "total_incidents_auto_resolved": 3, "total_incidents_manual_escalated": 3, "total_incidents_reassigned": 4, "total_incidents_timeout_escalated": 1, "total_interruptions": 1, "total_notifications": 23, "total_off_hour_interruptions": 3, "total_sleep_hour_interruptions": 1, "total_snoozed_seconds": 341, "total_user_defined_engaged_seconds": 124, "up_time_pct": 9.124123 }, { "distinct_responder_count": 1, "escalation_policy_id": "PDESCP2", "escalation_policy_name": "Escalation Policy 2", "mean_assignment_count": 1, "mean_engaged_seconds": 81, "mean_engaged_user_count": 63, "mean_seconds_to_engage": 41, "mean_seconds_to_first_ack": 380, "mean_seconds_to_mobilize": 81, "mean_seconds_to_resolve": 3591, "mean_user_defined_engaged_seconds": 81, "team_id": "PDTEAM1", "team_name": "Team 1", "total_business_hour_interruptions": 5, "total_engaged_seconds": 124, "total_escalation_count": 20, "total_incident_count": 21, "total_incidents_acknowledged": 78, "total_incidents_auto_resolved": 3, "total_incidents_manual_escalated": 3, "total_incidents_reassigned": 4, "total_incidents_timeout_escalated": 1, "total_interruptions": 1, "total_notifications": 23, "total_off_hour_interruptions": 3, "total_sleep_hour_interruptions": 1, "total_snoozed_seconds": 341, "total_user_defined_engaged_seconds": 124, "up_time_pct": 9.124123 } ], "filters": { "created_at_start": "2023-06-10T00:00:00Z", "created_at_end": "2023-06-12T00:00:00Z", "urgency": "high", "major": true, "escalation_policy_ids": [ "PDESCP1", "PDESCP2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-escalation-policy-all # Get aggregated metrics for all escalation policies `POST https://api.pagerduty.com/analytics/metrics/incidents/escalation_policies/all` Provides aggregated metrics across all escalation policies. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#escalation-policy-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-17T00:00:00-07:00", "created_at_end": "2023-07-01T23:59:59-07:00", "escalation_policy_ids": [ "PDESCP1", "PDESCP2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for escalation policies that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].distinct_responder_count` | integer | | Distinct count of responders who engaged in incidents on the escalation policy. | | `data[].escalation_policy_id` | string | | ID of the escalation policy the incident was last assigned to. Not included when aggregating by all. | | `data[].escalation_policy_name` | string | | Name of the escalation policy the incident was last assigned to. Not included when aggregating by all. | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range that the metrics were calculated for. Only included when an aggregate unit is specified in the request. | | `data[].team_id` | string | | ID of the team the incident was assigned to. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team the incident was assigned to. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Not included when aggregating by all. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "data": [ { "distinct_responder_count": 1, "mean_assignment_count": 1, "mean_engaged_seconds": 81, "mean_engaged_user_count": 63, "mean_seconds_to_engage": 41, "mean_seconds_to_first_ack": 380, "mean_seconds_to_mobilize": 81, "mean_seconds_to_resolve": 3591, "mean_user_defined_engaged_seconds": 81, "total_business_hour_interruptions": 5, "total_engaged_seconds": 124, "total_escalation_count": 20, "total_incident_count": 21, "total_incidents_acknowledged": 78, "total_incidents_auto_resolved": 3, "total_incidents_manual_escalated": 3, "total_incidents_reassigned": 4, "total_incidents_timeout_escalated": 1, "total_interruptions": 1, "total_notifications": 23, "total_off_hour_interruptions": 3, "total_sleep_hour_interruptions": 1, "total_snoozed_seconds": 341, "total_user_defined_engaged_seconds": 124, "up_time_pct": 9.124123 } ], "filters": { "created_at_start": "2023-06-17T07:00:00Z", "created_at_end": "2023-07-02T06:59:59Z", "escalation_policy_ids": [ "PDESCP1", "PDESCP2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-service # Get aggregated service data `POST https://api.pagerduty.com/analytics/metrics/incidents/services` Provides aggregated metrics for incidents aggregated into units of time by service. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#services-list). Data can be aggregated by day, week or month in addition to by service, or provided just as a collection of aggregates for each service in the dataset for the entire period. If a unit is provided, each row in the returned dataset will include a 'range_start' timestamp. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-10T00:00:00-07:00", "created_at_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "major": true, "team_ids": [ "P3XUQ75" ], "service_ids": [ "PPSCXAN" ] }, "aggregate_unit": "day", "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for services that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request. | | `data[].service_id` | string | | ID of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].service_name` | string | | Name of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].team_id` | string | | ID of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours. Sleep hours: 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Only included when aggregating by team, escalation policy, service, or all services. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "aggregate_unit": "day", "data": [ { "mean_assignment_count": 1, "mean_engaged_seconds": 366, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 81, "mean_seconds_to_first_ack": 63, "mean_seconds_to_mobilize": 41, "mean_seconds_to_resolve": 380, "mean_user_defined_engaged_seconds": 366, "range_start": "2023-06-11T00:00:00", "service_id": "PPSCXAN", "service_name": "Critical Prod Service 1", "team_id": "P3XUQ75", "team_name": "Engineering", "total_business_hour_interruptions": 81, "total_engaged_seconds": 3591, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 342, "total_off_hour_interruptions": 20, "total_sleep_hour_interruptions": 21, "total_snoozed_seconds": 78, "total_user_defined_engaged_seconds": 3591, "up_time_pct": 99.92677595628416 }, { "mean_assignment_count": 12, "mean_engaged_seconds": 432, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 77, "mean_seconds_to_first_ack": 32, "mean_seconds_to_mobilize": 32, "mean_seconds_to_resolve": 87, "mean_user_defined_engaged_seconds": 432, "range_start": "2023-06-10T00:00:00", "service_id": "PPSCXAN", "service_name": "Critical Prod Service 1", "team_id": "P3XUQ75", "team_name": "Engineering", "total_business_hour_interruptions": 12, "total_engaged_seconds": 3645, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 32, "total_off_hour_interruptions": 42, "total_sleep_hour_interruptions": 3, "total_snoozed_seconds": 123, "total_user_defined_engaged_seconds": 3645, "up_time_pct": 99.234416 } ], "filters": { "created_at_start": "2023-06-10T00:00:00Z", "created_at_end": "2023-06-12T00:00:00Z", "team_ids": [ "P3XUQ75" ], "service_ids": [ "PPSCXAN" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-service-all # Get aggregated metrics for all services `POST https://api.pagerduty.com/analytics/metrics/incidents/services/all` Provides aggregated metrics across all services. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#services-list). > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-17T00:00:00-07:00", "created_at_end": "2023-07-01T23:59:59-07:00", "service_ids": [ "PQVUB8D", "PU2D9X3" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for services that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request. | | `data[].service_id` | string | | ID of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].service_name` | string | | Name of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].team_id` | string | | ID of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours. Sleep hours: 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Only included when aggregating by team, escalation policy, service, or all services. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "data": [ { "mean_assignment_count": 1, "mean_engaged_seconds": 366, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 81, "mean_seconds_to_first_ack": 63, "mean_seconds_to_mobilize": 41, "mean_seconds_to_resolve": 380, "mean_user_defined_engaged_seconds": 366, "total_business_hour_interruptions": 81, "total_engaged_seconds": 3591, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 342, "total_off_hour_interruptions": 20, "total_sleep_hour_interruptions": 21, "total_snoozed_seconds": 78, "total_user_defined_engaged_seconds": 3591, "up_time_pct": 99.92677595628416 } ], "filters": { "created_at_start": "2023-06-17T07:00:00Z", "created_at_end": "2023-07-02T06:59:59Z", "service_ids": [ "PQVUB8D", "PU2D9X3" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-team # Get aggregated team data `POST https://api.pagerduty.com/analytics/metrics/incidents/teams` Provides aggregated metrics for incidents aggregated into units of time by team. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#teams-list). Data can be aggregated by day, week or month in addition to by team, or provided just as a collection of aggregates for each team in the dataset for the entire period. If a unit is provided, each row in the returned dataset will include a 'range_start' timestamp. > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-10T00:00:00-07:00", "created_at_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "major": true, "team_ids": [ "P3XUQ75" ] }, "aggregate_unit": "day", "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for teams that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request. | | `data[].service_id` | string | | ID of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].service_name` | string | | Name of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].team_id` | string | | ID of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours. Sleep hours: 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Only included when aggregating by team, escalation policy, service, or all services. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "aggregate_unit": "day", "data": [ { "mean_assignment_count": 1, "mean_engaged_seconds": 366, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 81, "mean_seconds_to_first_ack": 63, "mean_seconds_to_mobilize": 41, "mean_seconds_to_resolve": 380, "mean_user_defined_engaged_seconds": 366, "range_start": "2023-06-11T00:00:00", "team_id": "P3XUQ75", "team_name": "Engineering", "total_business_hour_interruptions": 81, "total_engaged_seconds": 3591, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 342, "total_off_hour_interruptions": 20, "total_sleep_hour_interruptions": 21, "total_snoozed_seconds": 78, "total_user_defined_engaged_seconds": 3591, "up_time_pct": 99.92677595628416 }, { "mean_assignment_count": 12, "mean_engaged_seconds": 432, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 77, "mean_seconds_to_first_ack": 32, "mean_seconds_to_mobilize": 32, "mean_seconds_to_resolve": 87, "mean_user_defined_engaged_seconds": 432, "range_start": "2023-06-10T00:00:00", "team_id": "P3XUQ75", "team_name": "Engineering", "total_business_hour_interruptions": 12, "total_engaged_seconds": 3645, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 32, "total_off_hour_interruptions": 42, "total_sleep_hour_interruptions": 3, "total_snoozed_seconds": 123, "total_user_defined_engaged_seconds": 3645, "up_time_pct": 99.234416 } ], "filters": { "created_at_start": "2023-06-10T00:00:00Z", "created_at_end": "2023-06-12T00:00:00Z", "urgency": "high", "major": true, "team_ids": [ "P3XUQ75" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-incidents-team-all # Get aggregated metrics for all teams `POST https://api.pagerduty.com/analytics/metrics/incidents/teams/all` Provides aggregated metrics across all teams. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#teams-list). > A `team_ids` or `service_ids` filter is required for [user-level API keys](https://support.pagerduty.com/docs/using-the-api#section-generating-a-personal-rest-api-key) or keys generated through an OAuth flow. Account-level API keys do not have this requirement. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-10T00:00:00-07:00", "created_at_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "major": true, "team_ids": [ "P3XUQ75" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for teams that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_assignment_count` | integer | | Mean count of instances where responders were assigned an incident (including through reassignment or escalation) or accepted a responder request. | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_engaged_user_count` | integer | | Mean number of users who engaged with an incident. *Engaged* is defined as acknowledging an incident or accepting a responder request in it. | | `data[].mean_seconds_to_engage` | integer | | A measure of *people response time*. This metric measures the time from the first user engagement (acknowledge or responder accept) to the last. This metric is only used for incidents with **multiple responders**; for incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_first_ack` | integer | | Mean time between the start of an incident, and the first responder to acknowledge. | | `data[].mean_seconds_to_mobilize` | integer | | Mean time between the start of an incident, and the last additional responder to acknowledge. For incidents with one or no engaged users, this value is null. | | `data[].mean_seconds_to_resolve` | integer | | Mean time from when an incident was triggered until it was resolved. | | `data[].mean_user_defined_engaged_seconds` | integer | | Mean engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].range_start` | string | | Start of the date range for which the metrics were calculated. Only included when an aggregate unit is specified in the request. | | `data[].service_id` | string | | ID of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].service_name` | string | | Name of the service. Only included when aggregating by service. Not included when aggregating by all. | | `data[].team_id` | string | | ID of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].team_name` | string | | Name of the team to which the incident was assigned. Not included when aggregating by all. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_escalation_count` | integer | | Total count of instances where an incident is escalated between responders assigned to an escalation policy. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_auto_resolved` | | | The total count of incidents that were resolved automatically. This count includes incidents resolved via an integration and those that were [auto-resolved in PagerDuty](https://support.pagerduty.com/docs/configurable-service-settings#auto-resolution). | | `data[].total_incidents_manual_escalated` | integer | | The total count of incidents that were manually escalated. | | `data[].total_incidents_reassigned` | integer | | The total count of incidents that were reassigned. | | `data[].total_incidents_timeout_escalated` | integer | | The total count of incidents that were escalated due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours. Sleep hours: 10pm-8am every day, based on the user’s time zone. | | `data[].total_snoozed_seconds` | integer | | Total number of seconds incidents were snoozed. | | `data[].total_user_defined_engaged_seconds` | integer | | Total engaged time across all responders. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. This metric uses the edited incident response effort values that [users have defined](https://support.pagerduty.com/docs/edit-incidents#edit-incident-duration), if they exist. | | `data[].up_time_pct` | number | | The percentage of time in the defined date range that the service was not interrupted by a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents). Only included when aggregating by team, escalation policy, service, or all services. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.pd_advance_used` | boolean | | If true, only incidents where PD Advance was used will be included in the results, and vice versa. If omitted, all incidents will be included. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | Example: Example Response ```json { "data": [ { "mean_assignment_count": 1, "mean_engaged_seconds": 366, "mean_engaged_user_count": 1, "mean_seconds_to_engage": 81, "mean_seconds_to_first_ack": 63, "mean_seconds_to_mobilize": 41, "mean_seconds_to_resolve": 380, "mean_user_defined_engaged_seconds": 366, "total_business_hour_interruptions": 81, "total_engaged_seconds": 3591, "total_escalation_count": 5, "total_incident_count": 124, "total_incidents_acknowledged": 1, "total_incidents_auto_resolved": 12, "total_incidents_manual_escalated": 9, "total_incidents_reassigned": 1, "total_incidents_timeout_escalated": 4, "total_interruptions": 1, "total_notifications": 342, "total_off_hour_interruptions": 20, "total_sleep_hour_interruptions": 21, "total_snoozed_seconds": 78, "total_user_defined_engaged_seconds": 3591 } ], "filters": { "created_at_start": "2023-06-10T00:00:00Z", "created_at_end": "2023-06-12T00:00:00Z", "urgency": "high", "major": true, "team_ids": [ "P3XUQ75" ] }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-pd-advance-usage-features # Get aggregated PD Advance usage data `POST https://api.pagerduty.com/analytics/metrics/pd_advance_usage/features` Provides aggregated metrics for the usage of PD Advance. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any PD Advance usage with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any PD Advance usage with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.incident_created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with incident_created_at_end is one year. | | `filters.incident_created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with incident_created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | Example: Example Request ```json { "filters": { "incident_created_at_start": "2024-01-01T00:00:00-05:00", "incident_created_at_end": "2024-01-31T00:00:00-05:00", "urgency": "high", "major": true }, "time_zone": "Etc/UTC" } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].feature_id` | string | | Which feature of PD Advance was used. | | `data[].total_credits_used` | integer | | How many credits were used by this feature. | | `data[].total_use_count` | integer | | How many times this feature was used. | | `data[].total_proactive_credits_used` | integer | | How many of the credits used were initiated by PD Advance rather than a user. | | `data[].total_proactive_use_count` | integer | | How many times this feature was initiated by PD Advance rather than a user. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.created_at_start` | string | | Accepts an ISO8601 DateTime string. Any PD Advance usage with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with created_at_end is one year. | | `filters.created_at_end` | string | | Accepts an ISO8601 DateTime string. Any PD Advance usage with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with created_at_start is one year. | | `filters.incident_created_at_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with incident_created_at_end is one year. | | `filters.incident_created_at_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with incident_created_at_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.major` | boolean | | A boolean flag including whether results should contain *only* [major incidents](https://support.pagerduty.com/docs/operational-reviews#major-incidents), or exclude major incidents. If no value is provided all incidents will be included. | | `filters.min_ackowledgements` | integer | | An integer that sets the requirement for the minimum number of acknowledgements to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 acknowledgement. If no value is provided, all incidents will be included. | | `filters.min_timeout_escalations` | integer | | An integer that sets the requirement for the minimum number of timeout escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 timeout escalation. If no value is provided, all incidents will be included. | | `filters.min_manual_escalations` | integer | | An integer that sets the requirement for the minimum number of manual escalations to occur on an incident. For example, setting this to 1 will return only incidents that have at least 1 manual escalation. If no value is provided, all incidents will be included. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.service_ids` | array of string | | An array of service IDs. Only incidents related to these services will be included in the results. If omitted, all services the requestor has access to will be included in the results. | | `filters.escalation_policy_ids` | array of string | | An array of escalation policy IDs. Only incidents related to these escalation policies will be included in the results. If omitted, all escalation policies the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | Example: Example Response ```json { "data": [ { "feature_id": "genai_incident_summarization", "total_credits_used": 16, "total_use_count": 8, "total_proactive_credits_used": 0, "total_proactive_use_count": 0 }, { "feature_id": "genai_assist_bot", "total_credits_used": 1, "total_use_count": 1, "total_proactive_credits_used": 0, "total_proactive_use_count": 0 }, { "feature_id": "genai_status_updates", "total_credits_used": 48, "total_use_count": 16, "total_proactive_credits_used": 0, "total_proactive_use_count": 0 }, { "feature_id": "genai_knowledge_base", "total_credits_used": 18, "total_use_count": 9, "total_proactive_credits_used": 0, "total_proactive_use_count": 0 }, { "feature_id": "genai_incident_insight", "total_credits_used": 96, "total_use_count": 84, "total_proactive_credits_used": 0, "total_proactive_use_count": 36 } ], "filters": { "incident_created_at_end": "2024-10-31T00:00:00Z", "incident_created_at_start": "2024-10-01T00:00:00Z" }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-responders-all # Get aggregated metrics for all responders `POST https://api.pagerduty.com/analytics/metrics/responders/all` Provides aggregated incident metrics for all selected responders. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#responders-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.date_range_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with date_range_end is one year. | | `filters.date_range_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with date_range_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.responder_ids` | array of string | | An array of responder IDs. Only incidents related to these responders will be included in the results. If omitted, all responders the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | Example: Example Request ```json { "filters": { "date_range_start": "2023-06-10T00:00:00-07:00", "date_range_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "responder_ids": [ "PDUSER1", "PDUSER2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for responders that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders for incidents that match the given filters. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_time_to_acknowledge_seconds` | integer | | The average time between when an incident is first assigned to a user and when the incident is first acknowledged by that user. Reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].responder_id` | integer | | ID of the responder (user). Not included when aggregating by all responders. | | `data[].responder_name` | string | | Name of the responder (user). Not included when aggregating by all responders. | | `data[].team_id` | string | | ID of the team associated with the responder. Not included when aggregating by all responders. | | `data[].team_name` | string | | Name of the team associated with the responder. Not included when aggregating by all responders. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders for incidents. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged by the user. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_manual_escalated_from` | integer | | The total count of the user’s assigned incidents that were manually escalated away from a user without acknowledgement. | | `data[].total_incidents_manual_escalated_to` | integer | | The total count of incidents the user was manually escalated to. | | `data[].total_incidents_reassigned_from` | integer | | The total count of a user's assigned incidents that were reassigned away from the user to another user or escalation policy. | | `data[].total_incidents_reassigned_to` | integer | | The total count of incidents the user was reassigned to. | | `data[].total_incidents_timeout_escalated_from` | integer | | The total count of the user’s assigned incidents that were escalated due to timeouts. | | `data[].total_incidents_timeout_escalated_to` | integer | | The total count of incidents the user was escalated to due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_seconds_on_call` | integer | | Total seconds the responder was on call. | | `data[].total_seconds_on_call_level_1` | integer | | Total seconds the responder was on call at level 1 of their escalation policy. | | `data[].total_seconds_on_call_level_2_plus` | integer | | Total seconds the responder was on call at level 2 or higher of their escalation policy. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.date_range_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with date_range_end is one year. | | `filters.date_range_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with date_range_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.responder_ids` | array of string | | An array of responder IDs. Only incidents related to these responders will be included in the results. If omitted, all responders the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | Example: Example Response ```json { "data": [ { "mean_engaged_seconds": 366, "mean_time_to_acknowledge_seconds": 1, "total_business_hour_interruptions": 81, "total_engaged_seconds": 63, "total_incident_count": 41, "total_incidents_acknowledged": 380, "total_incidents_manual_escalated_from": 81, "total_incidents_manual_escalated_to": 3591, "total_incidents_reassigned_from": 5, "total_incidents_reassigned_to": 124, "total_incidents_timeout_escalated_from": 20, "total_incidents_timeout_escalated_to": 21, "total_interruptions": 4, "total_notifications": 78, "total_off_hour_interruptions": 23, "total_seconds_on_call": 604799, "total_seconds_on_call_level_1": 126000, "total_seconds_on_call_level_2_plus": 604799, "total_sleep_hour_interruptions": 0 } ], "filters": { "date_range_start": "2023-06-10T00:00:00Z", "date_range_end": "2023-06-12T00:00:00Z", "responder_ids": [ "PDUSER1", "PDUSER2" ], "urgency": "high" }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-responders-team # Get responder data aggregated by team `POST https://api.pagerduty.com/analytics/metrics/responders/teams` Provides incident metrics aggregated by responder. Example metrics include Seconds to Resolve, Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#responders-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.date_range_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with date_range_end is one year. | | `filters.date_range_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with date_range_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.responder_ids` | array of string | | An array of responder IDs. Only incidents related to these responders will be included in the results. If omitted, all responders the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | Example: Example Request ```json { "filters": { "date_range_start": "2023-06-10T00:00:00-07:00", "date_range_end": "2023-06-11T23:59:59-07:00", "urgency": "high", "responder_ids": [ "PDUSER1", "PDUSER2" ] }, "time_zone": "Etc/UTC" } ``` ## Response 200 Only returns data for responders and teams that match the filters and have data. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].mean_engaged_seconds` | integer | | Mean engaged time across all responders for incidents that match the given filters. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].mean_time_to_acknowledge_seconds` | integer | | The average time between when an incident is first assigned to a user and when the incident is first acknowledged by that user. Reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].responder_id` | integer | | ID of the responder (user). Not included when aggregating by all responders. | | `data[].responder_name` | string | | Name of the responder (user). Not included when aggregating by all responders. | | `data[].team_id` | string | | ID of the team associated with the responder. Not included when aggregating by all responders. | | `data[].team_name` | string | | Name of the team associated with the responder. Not included when aggregating by all responders. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders for incidents. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_incident_count` | integer | | The total number of incidents that were created. | | `data[].total_incidents_acknowledged` | integer | | The total count of assigned incidents acknowledged by the user. Only explicit incident acknowledgment counts; reassign, resolve, and escalation actions do not imply acknowledgement. | | `data[].total_incidents_manual_escalated_from` | integer | | The total count of the user’s assigned incidents that were manually escalated away from a user without acknowledgement. | | `data[].total_incidents_manual_escalated_to` | integer | | The total count of incidents the user was manually escalated to. | | `data[].total_incidents_reassigned_from` | integer | | The total count of a user's assigned incidents that were reassigned away from the user to another user or escalation policy. | | `data[].total_incidents_reassigned_to` | integer | | The total count of incidents the user was reassigned to. | | `data[].total_incidents_timeout_escalated_from` | integer | | The total count of the user’s assigned incidents that were escalated due to timeouts. | | `data[].total_incidents_timeout_escalated_to` | integer | | The total count of incidents the user was escalated to due to timeouts. | | `data[].total_interruptions` | integer | | Total number of unique interruptions. | | `data[].total_notifications` | integer | | The total count of incident notifications sent via email, SMS, phone call and push. | | `data[].total_off_hour_interruptions` | integer | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_seconds_on_call` | integer | | Total seconds the responder was on call. | | `data[].total_seconds_on_call_level_1` | integer | | Total seconds the responder was on call at level 1 of their escalation policy. | | `data[].total_seconds_on_call_level_2_plus` | integer | | Total seconds the responder was on call at level 2 or higher of their escalation policy. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `filters` | object | | Accepts a set of filters to apply to the Incidents before aggregating. Any incidents that do not match the included filters will be omitted from the results. | | `filters.date_range_start` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at less than this value will be omitted from the results. The maximum supported time range in conjunction with date_range_end is one year. | | `filters.date_range_end` | string | | Accepts an ISO8601 DateTime string. Any incidents with a created_at greater than or equal to this value will be omitted from the results. The maximum supported time range in conjunction with date_range_start is one year. | | `filters.urgency` | string | | Any incidents whose urgency does not match the provided string will be omitted from the results. One of: `high`, `low`. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents related to these teams will be included in the results. If omitted, all teams the requestor has access to will be included in the results. | | `filters.responder_ids` | array of string | | An array of responder IDs. Only incidents related to these responders will be included in the results. If omitted, all responders the requestor has access to will be included in the results. | | `filters.priority_ids` | array of string | | An array of priority IDs. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `filters.priority_names` | array of string | | An array of user-defined priority names. Only incidents with these priorities will be included in the results. If omitted, all priorities will be included in the results. | | `time_zone` | string | | The time zone to use for the results and grouping. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. | Example: Example Response ```json { "data": [ { "mean_engaged_seconds": 366, "mean_time_to_acknowledge_seconds": 1, "responder_id": "PDUSER1", "responder_name": "User 1", "team_id": "PPSCXAN", "team_name": "Best Team A #1", "total_business_hour_interruptions": 81, "total_engaged_seconds": 63, "total_incident_count": 41, "total_incidents_acknowledged": 380, "total_incidents_manual_escalated_from": 81, "total_incidents_manual_escalated_to": 3591, "total_incidents_reassigned_from": 5, "total_incidents_reassigned_to": 124, "total_incidents_timeout_escalated_from": 20, "total_incidents_timeout_escalated_to": 21, "total_interruptions": 4, "total_notifications": 78, "total_off_hour_interruptions": 23, "total_seconds_on_call": 604799, "total_seconds_on_call_level_1": 126000, "total_seconds_on_call_level_2_plus": 604799, "total_sleep_hour_interruptions": 0 }, { "mean_engaged_seconds": 366, "mean_time_to_acknowledge_seconds": 1, "responder_id": "PDUSER2", "responder_name": "User 2", "team_id": "PPSCXAN", "team_name": "Best Team A #1", "total_business_hour_interruptions": 81, "total_engaged_seconds": 63, "total_incident_count": 41, "total_incidents_acknowledged": 380, "total_incidents_manual_escalated_from": 81, "total_incidents_manual_escalated_to": 3591, "total_incidents_reassigned_from": 5, "total_incidents_reassigned_to": 124, "total_incidents_timeout_escalated_from": 20, "total_incidents_timeout_escalated_to": 21, "total_interruptions": 6, "total_notifications": 78, "total_off_hour_interruptions": 23, "total_seconds_on_call": 120000, "total_seconds_on_call_level_1": 120000, "total_seconds_on_call_level_2_plus": 0, "total_sleep_hour_interruptions": 0 } ], "filters": { "date_range_start": "2023-06-10T00:00:00Z", "date_range_end": "2023-06-12T00:00:00Z", "responder_ids": [ "PDUSER1", "PDUSER2" ], "urgency": "high" }, "time_zone": "Etc/UTC" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-metrics-users-all # Get aggregated metrics for all users `POST https://api.pagerduty.com/analytics/metrics/users/all` Provides aggregated metrics across all users within their account. This endpoint provides summary statistics about user activity and performance. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | | | `filters.created_at_start` | string (date-time) | | The start of the date range to search. | | `filters.created_at_end` | string (date-time) | | The end of the date range to search. | | `filters.team_ids` | array of string | | An array of team IDs. Only users belonging to these teams will be included in results. | | `filters.user_ids` | array of string | | An array of user IDs. Only these users will be included in results. | | `filters.role_ids` | array of string | | An array of role IDs. Only users with these roles will be included in results. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. Default: `desc`. | | `order_by` | string | | The column that was used for ordering the results. Default: `user_id`. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | | `limit` | integer | | The maximum number of results to return per page. The default (and maximum allowed value) is 1000. Default: `1000`. | | `starting_after` | string \| null | | A cursor used for pagination. Starting after cursor provides the next set of results in forward pagination order. | | `ending_before` | string \| null | | A cursor used for pagination. Ending before cursor provides the previous set of results in reverse pagination order. | Example: Example Request ```json { "filters": { "created_at_start": "2024-08-07T00:00:00-07:00", "created_at_end": "2025-08-05T23:59:59-07:00" }, "time_zone": "America/Chicago" } ``` ## Response 200 Returns user metrics aggregated across the account ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `data` | array of object | | | | `data[].total_downloaded_mobile_app_count` | integer | | The number of users who have downloaded the mobile app. | | `data[].total_downloaded_mobile_app_percentage` | number (float) | | The percentage of users who have downloaded the mobile app. | | `data[].total_on_escalation_policy_count` | integer | | The number of users who are on at least one escalation policy. | | `data[].total_on_escalation_policy_percentage` | number (float) | | The percentage of users who are on at least one escalation policy. | | `data[].total_signed_up_count` | integer | | The number of users who have signed up (completed onboarding). | | `data[].total_signed_up_percentage` | number (float) | | The percentage of users who have signed up. | | `data[].total_user_count` | integer | | The total number of users in the account that match the filters. | | `data[].total_with_notification_methods_count` | integer | | The number of users who have at least one notification method configured. | | `data[].total_with_notification_methods_percentage` | number (float) | | The percentage of users who have at least one notification method configured. | | `filters` | object | | | | `filters.created_at_start` | string (date-time) | | The start of the date range used for filtering. | | `filters.created_at_end` | string (date-time) | | The end of the date range used for filtering. | | `filters.team_ids` | array of string | | The team IDs used for filtering. | | `time_zone` | string | | The time zone used for the results. | Example: Example Response ```json { "data": [ { "total_downloaded_mobile_app_count": 0, "total_downloaded_mobile_app_percentage": 0, "total_on_escalation_policy_count": 0, "total_on_escalation_policy_percentage": 0, "total_signed_up_count": 14, "total_signed_up_percentage": 70, "total_user_count": 20, "total_with_notification_methods_count": 5, "total_with_notification_methods_percentage": 25 } ], "filters": { "created_at_start": "2024-08-07T07:00:00Z", "created_at_end": "2025-08-06T06:59:59Z" }, "time_zone": "America/Chicago" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-responder-incidents # Get raw incidents for a single responder_id `POST https://api.pagerduty.com/analytics/raw/responders/{responder_id}/incidents` Provides enriched incident data and metrics for a specific responder. Example metrics include Mean Seconds to Resolve, Mean Seconds to Engage, Snoozed Seconds, and Sleep Hour Interruptions. Metric definitions can be found in our [Knowledge Base](https://support.pagerduty.com/docs/insights#incidents-list). > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `responder_id` | string | yes | The ID of the responder. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | Filters the result, only show incidents that match the conditions passed in the filter. | | `filters.created_at_start` | string | | Filters the result, showing only the incidents where the creation timestamp is greater than the filter value. | | `filters.created_at_end` | string | | Filters the result, showing only the incidents where the creation timestamp is less than the filter value. | | `filters.urgency` | string | | Filters the result, showing only the incidents where urgency matches the filter value. | | `filters.major` | boolean | | An incident is classified as a [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) if it has one of the two highest priorities, or if multiple responders are added and acknowledge the incident. | | `filters.team_ids` | array of string | | An array of team IDs. Only incidents that are assigned to a member of these teams will be returned. Account must have the teams ability to use this parameter. | | `filters.service_ids` | array of string | | An array of service IDs. Only results related to these services will be returned. | | `filters.priority_ids` | array of string | | The priority_ids filter applied to the results. | | `filters.priority_names` | array of string | | The priority_names filter applied to the results. | | `filters.incident_type_ids` | array of string | | Filter incidents by specific incident type IDs. Only incidents matching the given IDs will be returned. | | `starting_after` | string | | A cursor to indicate the reference point that the results should follow. | | `ending_before` | string | | A cursor to indicate the reference point that the results should precede. | | `order` | string | | The order in which to display the results; asc for ascending, desc for descending. Defaults to `desc`. One of: `asc`, `desc`. | | `order_by` | string | | The column to use for ordering the results. Defaults to `incident_created_at`. One of: `incident_created_at`. | | `limit` | integer | | Number of results to include in each batch. Limits between 1 to 1000 are accepted. Greater than 0. Maximum: 1000. | | `time_zone` | string | | The time zone to use for the results. | Example: Example Request ```json { "filters": { "created_at_start": "2023-06-10T00:00:00-07:00", "created_at_end": "2023-06-11T23:59:59-07:00", "incident_type_ids": [ "PIJ90N7", "PKL73Z2" ] }, "responder_id": "PDUSER1", "limit": 100, "order": "asc", "order_by": "incident_created_at", "time_zone": "Etc/UTC" } ``` ## Response 200 ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `first` | string | | Cursor to identify the first object in the response. | | `last` | string | | Cursor to identify the last object in the response. | | `responder_id` | string | | The Responder ID passed into the request. | | `limit` | integer | | Number of results to include in the batch. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. One of: `incident_created_at`. | | `time_zone` | string | | The time zone that the results are in. | | `filters` | object | | A collection of filters that were applied to the results. | | `filters.created_at_start` | string | | The lower boundary for the created_at range filter applied to the results. | | `filters.created_at_end` | string | | The upper boundary for the created_at range filter applied to the results. | | `filters.urgency` | string | | The urgency filter applied to the results. One of: `high`, `low`. | | `filters.major` | boolean | | The [major incident](https://support.pagerduty.com/docs/operational-reviews#major-incidents) filter applied to the results. | | `filters.team_ids` | array of string | | The team_ids filter applied to the results. | | `filters.service_ids` | array of string | | The service_ids filter applied to the results. | | `filters.priority_ids` | array of string | | The priority_ids filter applied to the results. Max items: 5. | | `filters.priority_names` | array of string | | The priority_names filter applied to the results. Max items: 5. | | `filters.incident_type_ids` | array of string | | The incident_type_ids filter applied to the results. | | `data` | array of object | | | | `data[].incident_created_at` | string | | Timestamp of when the incident was created. | | `data[].incident_description` | string | | The incident description. | | `data[].incident_id` | string | | Incident ID. | | `data[].incident_number` | integer | | The PagerDuty incident number. | | `data[].incident_priority_id` | string \| null | | ID of the incident's priority level. | | `data[].incident_priority_name` | string \| null | | The user-provided short name of the priority. | | `data[].incident_priority_order` | integer \| null | | The numerical value used to sort priorities. Higher values are higher priority. | | `data[].incident_urgency` | string | | Notification level. | | `data[].mean_time_to_acknowledge_seconds` | integer | | Mean time from this user being assigned to an incident until this user acknowledges the incident. | | `data[].responder_id` | string | | ID of the responder. | | `data[].responder_name` | string | | Name of the responder. | | `data[].service_id` | string | | ID of the service that the incident triggered on. | | `data[].service_name` | string | | Name of the service that the incident triggered on. | | `data[].service_team_id` | string \| null | | ID of the team that owns the related service. | | `data[].service_team_name` | string \| null | | Name of the team that owns the related service. | | `data[].total_acknowledgements` | integer | | Total acknowledgements from the responder on the incident. | | `data[].total_business_hour_interruptions` | integer | | Total number of unique interruptions during business hours; 8am-6pm Mon-Fri, based on the user’s time zone. | | `data[].total_engaged_seconds` | integer | | Total engaged time across all responders for incidents. Engaged time is measured from the time a user engages with an incident (by acknowledging or accepting a responder request) until the incident is resolved. This may include periods in which the incidents were snoozed. | | `data[].total_interruptions` | integer | | Total number of unique interruptions for the responder during the incident. | | `data[].total_manual_escalations_from` | integer | | Total times the responder was manually escalated away from the incident. | | `data[].total_manual_escalations_to` | integer | | Total times the responder was manually escalated to the incident. | | `data[].total_off_hour_interruptions` | string | | Total number of unique interruptions during off hours; 6pm-10pm Mon-Fri and all day Sat-Sun, based on the user’s time zone. | | `data[].total_reassignments_from` | integer | | Total times the responder was reassigned away from the incident. | | `data[].total_reassignments_to` | integer | | Total times the responder was reassigned to the incident. | | `data[].total_sleep_hour_interruptions` | integer | | Total number of unique interruptions during sleep hours; 10pm-8am every day, based on the user’s time zone. | | `data[].total_timeout_escalations_from` | integer | | Total times the responder was escalated away from the incident due to timeout. | | `data[].total_timeout_escalations_to` | integer | | Total times the responder was escalated to the incident due to timeout. | Example: Example Response ```json { "responder_id": "PDUSER1", "limit": 100, "order": "asc", "order_by": "incident_created_at", "time_zone": "Etc/UTC", "data": [ { "incident_created_at": "2023-06-10T22:08:35", "incident_description": 30, "incident_id": "QPDINCIDENT1", "incident_number": 123456, "incident_priority_id": "PZOZQXA", "incident_priority_name": "P1", "incident_priority_order": 67108864, "incident_urgency": 75, "mean_time_to_acknowledge_seconds": 2, "responder_id": "PDUSER1", "responder_name": "User 1", "service_id": "PDSERV1", "service_name": "Service 1", "service_team_id": "PDTEAM1", "service_team_name": "Team 1", "total_acknowledgements": 12, "total_business_hour_interruptions": 3, "total_engaged_seconds": 244, "total_interruptions": 2, "total_manual_escalations_from": 5, "total_manual_escalations_to": 1, "total_off_hour_interruptions": 0, "total_reassignments_from": 0, "total_reassignments_to": 0, "total_sleep_hour_interruptions": 0, "total_timeout_escalations_from": 0, "total_timeout_escalations_to": 0 }, { "incident_created_at": "2023-06-11T22:08:35", "incident_description": 30, "incident_id": "QPDINCIDENT2", "incident_number": 123456, "incident_priority_id": "PZOZQXA", "incident_priority_name": "P1", "incident_priority_order": 67108864, "incident_urgency": 75, "mean_time_to_acknowledge_seconds": 2, "responder_id": "PDUSER1", "responder_name": "User 1", "service_id": "PDSERV2", "service_name": "Service 2", "service_team_id": "PDTEAM1", "service_team_name": "Team 1", "total_acknowledgements": 12, "total_business_hour_interruptions": 3, "total_engaged_seconds": 945, "total_interruptions": 2, "total_manual_escalations_from": 5, "total_manual_escalations_to": 1, "total_off_hour_interruptions": 0, "total_reassignments_from": 0, "total_reassignments_to": 0, "total_sleep_hour_interruptions": 0, "total_timeout_escalations_from": 0, "total_timeout_escalations_to": 0 } ] } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/analytics/get-analytics-users # Get raw user analytics data `POST https://api.pagerduty.com/analytics/raw/users` Allows users to retrieve a raw list of user analytics data within their account. This endpoint provides detailed data about user activity and account configuration. > **Note:** Data availability reflects [pipeline processing cycles](https://support.pagerduty.com/main/docs/insights#:~:text=Data%20Update%20Schedule) and is generally within 24 hours under normal conditions. Scoped OAuth requires: `analytics.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Parameters and filters to apply to the dataset. | Field | Type | Required | Description | |---|---|---|---| | `filters` | object | | | | `filters.created_at_start` | string (date-time) | | The start of the date range to search. | | `filters.created_at_end` | string (date-time) | | The end of the date range to search. | | `filters.team_ids` | array of string | | An array of team IDs. Only users belonging to these teams will be included in results. | | `filters.user_ids` | array of string | | An array of user IDs. Only these users will be included in results. | | `filters.role_ids` | array of string | | An array of role IDs. Only users with these roles will be included in results. | | `time_zone` | string | | The time zone to use for the results and grouping. Must be in tzdata format. See list of accepted values [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. Default: `desc`. | | `order_by` | string | | The column that was used for ordering the results. Default: `user_id`. | | `aggregate_unit` | string \| null | | The time unit to aggregate metrics by. If no value is provided, the metrics will be aggregated for the entire period. One of: `day`, `week`, `month`. | | `limit` | integer | | The maximum number of results to return per page. The default (and maximum allowed value) is 1000. Default: `1000`. | | `starting_after` | string \| null | | A cursor used for pagination. Starting after cursor provides the next set of results in forward pagination order. | | `ending_before` | string \| null | | A cursor used for pagination. Ending before cursor provides the previous set of results in reverse pagination order. | Example: Example Request ```json { "filters": { "created_at_start": "2025-01-01T00:00:00Z", "created_at_end": "2025-09-01T00:00:00Z" }, "limit": 10 } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `first` | string | | Cursor to identify the first object in the response. | | `last` | string | | Cursor to identify the last object in the response. | | `limit` | integer | | Number of results to include in the batch. | | `more` | boolean | | Indicates if there are more resources available than were returned. | | `order` | string | | The order in which the results were sorted; asc for ascending, desc for descending. One of: `asc`, `desc`. | | `order_by` | string | | The column that was used for ordering the results. Default: `name`. | | `filters` | object | | A collection of filters that were applied to the results. | | `filters.created_at_start` | string | | The lower boundary for the created_at range filter applied to the results. | | `filters.created_at_end` | string | | The upper boundary for the created_at range filter applied to the results. | | `filters.team_ids` | array of string | | The team_ids filter applied to the results. | | `filters.roles` | array of string | | The roles filter applied to the results. | | `time_zone` | string | | The time zone that the results are in. | | `data` | array of object | | | | `data[].id` | string | | Obfuscated ID of the user. | | `data[].user_name` | string | | Name of the user. | | `data[].email` | string | | Email of the user. | | `data[].account_id` | integer | | Account ID the user belongs to. | | `data[].description` | string \| null | | User description, if available. | | `data[].time_zone` | string \| null | | User's configured time zone. | | `data[].role` | string | | User's role in the account. | | `data[].team_id` | string \| null | | ID of the team the user belongs to, if any. | | `data[].team_name` | string \| null | | Name of the team the user belongs to, if any. | | `data[].created_at` | string (date-time) | | Timestamp indicating when the user was created. | | `data[].last_sign_in_at` | string \| null (date-time) | | Timestamp of the user's last sign-in, if available. | | `data[].default_notification_channel_count` | integer | | Number of notification channels configured for this user. | | `data[].escalation_policies_count` | integer | | Number of escalation policies this user is part of. | | `data[].schedules_count` | integer | | Number of schedules this user is part of. | | `data[].channel_types_configured` | array of string | | List of notification channel types configured for this user. | | `data[].team_count` | integer | | Number of teams this user belongs to. | | `data[].downloaded_mobile_app` | boolean | | Whether the user has downloaded the mobile app. | | `data[].notification_methods` | boolean | | Whether the user has notification methods configured. | | `data[].on_escalation_policy` | boolean | | Whether the user is part of any escalation policy. | | `data[].on_schedule` | boolean | | Whether the user is part of any schedule. | | `data[].signed_up` | boolean | | Whether the user has signed up (based on last_sign_in_at not being null). | Example: Example Response ```json { "data": [ { "id": "PAQ8IMO", "description": null, "time_zone": null, "role": "user", "account_id": 1454, "team_id": null, "team_name": null, "created_at": "2025-02-21T16:56:08", "email": "atest@pagerduty.com", "user_name": "Adam Test", "last_sign_in_at": "2025-03-04T09:30:51", "default_notification_channel_count": 0, "escalation_policies_count": 0, "schedules_count": 0, "channel_types_configured": [ "SlackChannel", "EmailChannel" ], "team_count": 0, "downloaded_mobile_app": false, "notification_methods": false, "on_escalation_policy": false, "on_schedule": false, "signed_up": true }, { "id": "PLNOYYJ", "description": null, "time_zone": "Europe/Lisbon", "role": "user", "account_id": 1454, "team_id": null, "team_name": null, "created_at": "2025-08-12T17:16:12", "email": "btest@pagerduty.com", "user_name": "B Test", "last_sign_in_at": "2025-09-03T12:05:29", "default_notification_channel_count": 1, "escalation_policies_count": 0, "schedules_count": 0, "channel_types_configured": [ "EmailChannel", "PushNotificationChannel", "SlackChannel", "SmsChannel", "PhoneChannel" ], "team_count": 0, "downloaded_mobile_app": true, "notification_methods": true, "on_escalation_policy": false, "on_schedule": false, "signed_up": true } ], "first": "eyJpZCI6IlBBUThJTU8iLCJ2YWx1ZSI6IkFkYW0gRGlvcCIsIm9yZGVyX2J5IjoibmFtZSJ9", "last": "eyJpZCI6IlBQNTlSRTAiLCJ2YWx1ZSI6IkFsbGlzb24gQ29ybGV5Iiwib3JkZXJfYnkiOiJuYW1lIn0=", "more": true, "limit": 10, "filters": { "created_at_start": "2025-01-01T00:00:00Z", "created_at_end": "2025-09-01T00:00:00Z" }, "time_zone": "Etc/UTC", "order": "asc", "order_by": "name" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/audit/list-audit-records # List audit records `GET https://api.pagerduty.com/audit/records` List audit trail records matching provided query params or default criteria. The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. Only admins, account owners, or global API tokens on PagerDuty account [pricing plans](https://www.pagerduty.com/pricing) with the "Audit Trail" feature can access this endpoint. For other role based access to audit records by resource ID, see the resource's API documentation. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | | `root_resource_types[]` | string | | Resource type filter for the root_resource. One of: `users`, `teams`, `schedules`, `escalation_policies`, `services`, `ip_allow_lists`. | | `actor_type` | string | | Actor type filter. One of: `user_reference`, `api_key_reference`, `app_reference`. | | `actor_id` | string | | Actor Id filter. Must be qualified by providing the `actor_type` param. | | `method_type` | string | | Method type filter. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `method_truncated_token` | string | | Method truncated_token filter. Must be qualified by providing the `method_type` param. | | `actions[]` | string | | Action filter. One of: `create`, `update`, `delete`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PDRECORDID1_TEAM_CREATED", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "111lDEOIH-534-4ljhLHJjh111", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference" } ], "method": { "type": "api_token", "truncated_token": "3usr" }, "root_resource": { "id": "PXASDFE", "type": "team_reference", "summary": "my DevOps team" }, "action": "create", "details": { "resource": { "id": "PXASDFE", "type": "team_reference", "summary": "my DevOps team" }, "fields": [ { "name": "teamName", "value": "DevOps team" } ] } }, { "id": "PDRECORDID2_USER_REMOVED_FROM_TEAM", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "222lDEOIH-534-4ljhLHJjh222", "remote_address": "201.19.20.19" }, "method": { "type": "api_token", "truncated_token": "2adm" }, "root_resource": { "id": "PRY9M8B", "type": "team_reference", "summary": "DevOps" }, "action": "update", "details": { "resource": { "id": "PRY9M8B", "type": "team_reference", "summary": "DevOps" }, "references": [ { "name": "members", "removed": [ { "id": "PRY9M8B", "type": "user_reference", "summary": "John Doe" } ] } ] } }, { "id": "PDRECORDID5_USERS_TEAM_ROLE_UPDATED", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "222lDEOIH-534-4ljhLHJjh222", "remote_address": "201.19.20.19" }, "method": { "type": "api_token", "truncated_token": "2adm" }, "root_resource": { "id": "PRY9M8B", "type": "team_reference", "summary": "DevOps" }, "action": "update", "details": { "resource": { "id": "PDUSER", "type": "user_reference", "summary": "John Snow" }, "fields": [ { "name": "team_role", "before_value": "observer", "value": "manager" } ] } }, { "id": "PDRECORDID3_USERS_NAME_AND_EMAIL_UPDATED", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "222lDEOIH-534-4ljhLHJjh222", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference" } ], "method": { "type": "identity_provider" }, "root_resource": { "id": "PDUSER", "type": "user_reference", "summary": "John Snow" }, "action": "update", "details": { "resource": { "id": "PDUSER", "type": "user_reference", "summary": "John Snow" }, "fields": [ { "name": "name", "before_value": "Bob Doe", "value": "Jon Snow" }, { "name": "email", "before_value": "bob.doe@domain.com", "value": "john.snow@domain.com" } ] } }, { "id": "PDRECORDID4_UPDATED_USERS_NOTIFICATION_RULE", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "222lDEOIH-534-4ljhLHJjh222", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference" } ], "method": { "type": "api_token", "truncated_token": "2adm" }, "root_resource": { "id": "PDUSER", "type": "user_reference", "summary": "John Snow" }, "action": "update", "details": { "resource": { "id": "PXOGWUS", "type": "assignment_notification_rule_reference", "summary": "0 minutes: channel P1IAAPZ" }, "fields": [ { "name": "start_delay_in_minutes", "before_value": "0", "value": "2" } ], "references": [ { "name": "contact_method", "removed": [ { "id": "POE6L88", "type": "push_notification_contact_method_reference", "summary": "Pixel 3" } ], "added": [ { "id": "P4GTUMK", "type": "sms_contact_method_reference", "summary": "Mobile" } ] } ] } } ], "next_cursor": null, "limit": 10 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-action # Create an Automation Action `POST https://api.pagerduty.com/automation_actions/actions` Create a Script, Process Automation, or Runbook Automation action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `action` | one of: object \| object | yes | | | `action.name` | string | yes | (option 1) Max length: 255. | | `action.description` | string | yes | (option 1) Max length: 1024. | | `action.action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `action.action_type` | string | yes | (option 1) One of: `script`, `process_automation`. | | `action.runner` | string | | (option 1) Max length: 36. | | `action.services` | array of object | | (option 1) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.teams` | array of object | | (option 1) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 1) | | `action.action_data_reference.script` | string | yes | Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `action.action_data_reference.invocation_command` | string | | The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `action.name` | string | yes | (option 2) Max length: 255. | | `action.description` | string | yes | (option 2) Max length: 1024. | | `action.action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `action.action_type` | string | yes | (option 2) One of: `script`, `process_automation`. | | `action.runner` | string | | (option 2) Max length: 36. | | `action.services` | array of object | | (option 2) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.teams` | array of object | | (option 2) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 2) | | `action.action_data_reference.process_automation_job_id` | string | yes | Max length: 36. | | `action.action_data_reference.process_automation_job_arguments` | string | | Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `action.action_data_reference.process_automation_node_filter` | string | | Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | Example: request ```json { "action": { "name": "Restart apache", "description": "Restarts apache on the us-west-2-shopping-cart host", "action_type": "script", "action_data_reference": { "script": "java --version" }, "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "services": [ { "id": "PRDRWUJ", "type": "service_reference" } ] } } ``` ## Response 201 Action information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `action` | one of: object \| object | yes | | | `action.id` | string | yes | (option 1) Read-only. | | `action.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 1) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 1) | | `action.description` | string | | (option 1) | | `action.action_type` | string | yes | (option 1) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 1) Max length: 36. | | `action.runner_type` | string | | (option 1) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 1) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 1) | | `action.privileges.permissions` | array of string | yes | | | `action.metadata` | object | | (option 1) | | `action.creation_time` | string (date-time) | yes | (option 1) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 1) The date/time. | | `action.last_run` | string (date-time) | | (option 1) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 1) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 1) Same fields as `action.action_data_reference` above. | | `action.teams` | array of object | | (option 1) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.id` | string | yes | (option 2) Read-only. | | `action.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 2) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 2) | | `action.description` | string | | (option 2) | | `action.action_type` | string | yes | (option 2) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 2) Max length: 36. | | `action.runner_type` | string | | (option 2) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 2) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 2) Same fields as `action.privileges` above. | | `action.metadata` | object | | (option 2) | | `action.creation_time` | string (date-time) | yes | (option 2) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 2) The date/time. | | `action.last_run` | string (date-time) | | (option 2) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 2) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 2) Same fields as `action.action_data_reference` above. | | `action.teams` | array of object | | (option 2) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "action": { "action_data_reference": { "script": "java --version" }, "action_type": "script", "type": "action", "creation_time": "2022-11-08T14:54:02.267989Z", "description": "Restarts apache on the us-west-2-shopping-cart host", "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "modify_time": "2022-11-08T14:54:02.267989Z", "name": "Restart apache", "only_invocable_on_unresolved_incidents": false, "allow_invocation_manually": true, "allow_invocation_from_event_orchestration": true, "map_to_all_services": false, "privileges": { "permissions": [ "read", "update", "delete", "invoke" ] }, "services": [ { "id": "PRDRWUJ", "type": "service_reference" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-action-invocation # Create an Invocation `POST https://api.pagerduty.com/automation_actions/actions/{id}/invocations` Invokes an Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `invocation` | object | yes | | | `invocation.metadata` | object | yes | | | `invocation.metadata.incident_id` | string | yes | | | `invocation.metadata.alert_id` | string | | | Example: request ```json { "invocation": { "metadata": { "incident_id": "Q2LAR4ADCXC8IB" } } } ``` ## Response 201 Created invocation ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `invocation` | object | yes | | | `invocation.id` | string | yes | Read-only. | | `invocation.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `invocation.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocation.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.action_snapshot` | object | yes | | | `invocation.action_snapshot.name` | string | yes | | | `invocation.action_snapshot.action_type` | string | yes | One of: `script`, `process_automation`. | | `invocation.action_snapshot.action_data_reference` | one of: object \| object | | | | `invocation.action_snapshot.action_data_reference.process_automation_job_id` | string | yes | (option 1) Max length: 36. | | `invocation.action_snapshot.action_data_reference.process_automation_job_arguments` | string | | (option 1) Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `invocation.action_snapshot.action_data_reference.process_automation_node_filter` | string | | (option 1) Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | | `invocation.action_snapshot.action_data_reference.script` | string | yes | (option 2) Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `invocation.action_snapshot.action_data_reference.invocation_command` | string | | (option 2) The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `invocation.runner_id` | string | yes | | | `invocation.timing` | array of object | yes | A list of state transitions with timestamps, sorted in ascending order by timestamp. Only the 'created' transition is guaranteed to exist at any time. | | `invocation.timing[].timestamp` | string (date-time) | yes | The date/time. | | `invocation.timing[].state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocation.duration` | integer | | The duration of the invocation's execution time. | | `invocation.state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocation.action_id` | string | yes | | | `invocation.metadata` | object | yes | | | `invocation.metadata.agent` | one of: object \| object \| object \| object | yes | | | `invocation.metadata.agent.id` | string | yes | (option 1) Read-only. | | `invocation.metadata.agent.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.agent.type` | string | yes | (option 1) One of: `user_reference`. | | `invocation.metadata.agent.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.agent.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.metadata.agent.id` | string | yes | (option 2) | | `invocation.metadata.agent.type` | string | yes | (option 2) | | `invocation.metadata.agent.id` | string | yes | (option 3) Read-only. | | `invocation.metadata.agent.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.agent.type` | string | yes | (option 3) One of: `account_reference`. | | `invocation.metadata.agent.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.agent.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.metadata.agent.id` | string | yes | (option 4) | | `invocation.metadata.agent.type` | string | yes | (option 4) | | `invocation.metadata.incident` | object | | | | `invocation.metadata.incident.id` | string | yes | Read-only. | | `invocation.metadata.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.incident.type` | string | yes | One of: `incident_reference`. | | `invocation.metadata.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "invocation": { "id": "01DBYD4A25RCXAXQDC9ZX0678V", "type": "invocation", "action_snapshot": { "name": "Restart apache", "action_type": "script", "action_data_reference": { "script": "print(\\Hello from a Python script!\\)", "invocation_command": "/usr/local/bin/python3" } }, "runner_id": "01COQFFNVWIONSLY8C66YTU2O5", "timing": [ { "timestamp": "2022-11-08T22:57:14.756Z", "state": "sent" } ], "duration": 23, "state": "sent", "action_id": "01DAW70HK24JZORNE0P9C2V1L9", "metadata": { "agent": { "id": "PT4KHLK", "type": "user_reference" }, "incident": { "id": "Q2LAR4ADCXC8IB", "type": "incident_reference" } } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-action-service-assocation # Associate an Automation Action with a service `POST https://api.pagerduty.com/automation_actions/actions/{id}/services` Associate an Automation Action with a service ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | | | `service.id` | string | yes | Read-only. | | `service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.type` | string | yes | One of: `service_reference`. | | `service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: request ```json { "service": { "id": "PRDRWUJ", "type": "service_reference" } } ``` ## Response 201 The action-service association was created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | Same fields as `service` above. | Example: response ```json { "service": { "id": "PRDRWUJ", "type": "service_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-action-team-association # Associate an Automation Action with a team `POST https://api.pagerduty.com/automation_actions/actions/{id}/teams` Associate an Automation Action with a team ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | | | `team.id` | string | yes | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | One of: `team_reference`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: request ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 201 The action-team association was created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | Same fields as `team` above. | Example: response ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-actions-runner # Create an Automation Action runner. `POST https://api.pagerduty.com/automation_actions/runners` Create a Process Automation or a Runbook Automation runner. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `runner` | one of: object \| object | yes | | | `runner.runner_type` | string | yes | (RunnerSidecarPostBody) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runner.name` | string | yes | (RunnerSidecarPostBody) Max length: 255. | | `runner.description` | string | yes | (RunnerSidecarPostBody) Max length: 1024. | | `runner.teams` | array of object | | (RunnerSidecarPostBody) The list of teams associated with the Runner. | | `runner.teams[].id` | string | yes | Read-only. | | `runner.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.teams[].type` | string | yes | One of: `team_reference`. | | `runner.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.runner_type` | string | yes | (RunnerRunbookPostBody) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runner.name` | string | yes | (RunnerRunbookPostBody) Max length: 255. | | `runner.description` | string | yes | (RunnerRunbookPostBody) Max length: 1024. | | `runner.runbook_base_uri` | string | yes | (RunnerRunbookPostBody) The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runner.runbook_api_key` | string | yes | (RunnerRunbookPostBody) The API key to connect to the Runbook server with. If omitted, the previously stored value will remain unchanged. Max length: 64. | | `runner.teams` | array of object | | (RunnerRunbookPostBody) The list of teams associated with the Runner. | | `runner.teams[].id` | string | yes | Read-only. | | `runner.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.teams[].type` | string | yes | One of: `team_reference`. | | `runner.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: request ```json { "runner": { "name": "us-west-2 prod sidecar runner", "description": "us-west-2 prod sidecar runner provisioned by SRE", "runner_type": "sidecar", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } } ``` ## Response 201 Runner information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `runner` | object | yes | | | `runner.id` | string | yes | Read-only. | | `runner.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `runner.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.runner_type` | string | yes | sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runner.name` | string | yes | | | `runner.description` | string | | | | `runner.last_seen` | string (date-time) | | | | `runner.status` | string | yes | Configured -- Runner has connected to the backend at least once NotConfigured -- Runner has never connected to backend. One of: `Configured`, `NotConfigured`. | | `runner.creation_time` | string (date-time) | yes | | | `runner.runbook_base_uri` | string | | The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runner.teams` | array of object | | The list of teams associated with the Runner. Read-only. | | `runner.teams[].id` | string | yes | Read-only. | | `runner.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.teams[].type` | string | yes | One of: `team_reference`. | | `runner.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.privileges` | object | | | | `runner.privileges.permissions` | array of string | yes | | | `runner.associated_actions` | object | | References to at most 3 actions associated with the Runner. Use appropriate endpoints to retrieve the full list of associated actions. | | `runner.associated_actions.actions` | array of object | yes | | | `runner.associated_actions.actions[].id` | string | yes | Read-only. | | `runner.associated_actions.actions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.associated_actions.actions[].type` | string | yes | One of: `action_reference`. | | `runner.associated_actions.actions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.associated_actions.actions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.associated_actions.more` | boolean | yes | Indicates whether more actions exist for the Runner. | | `runner.metadata` | object | | Additional metadata. | | `runner.secret` | string | | Secret used for authentication of sidecar runner_types. | Example: Response Example ```json { "runner": { "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "name": "us-west-2 prod sidecar runner", "summary": "us-west-2 prod sidecar runner", "type": "runner", "description": "us-west-2 prod sidecar runner provisioned by SRE", "creation_time": "2022-10-21T19:42:52.127369Z", "runner_type": "sidecar", "status": "Configured", "secret": "01DAZ9ZJ97OE23JUI6WH9XN7BK", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "privileges": { "permissions": [ "read", "update" ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/create-automation-actions-runner-team-association # Associate a runner with a team `POST https://api.pagerduty.com/automation_actions/runners/{id}/teams` Associate a runner with a team ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | | | `team.id` | string | yes | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | One of: `team_reference`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: request ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 201 The runner-team association that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | Same fields as `team` above. | Example: Response Example ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/delete-automation-action # Delete an Automation Action `DELETE https://api.pagerduty.com/automation_actions/actions/{id}` Delete an Automation Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/delete-automation-action-service-association # Disassociate an Automation Action from a service `DELETE https://api.pagerduty.com/automation_actions/actions/{id}/services/{service_id}` Disassociate an Automation Action from a service ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Ok. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/delete-automation-action-team-association # Disassociate an Automation Action from a team `DELETE https://api.pagerduty.com/automation_actions/actions/{id}/teams/{team_id}` Disassociate an Automation Action from a team ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `team_id` | string | yes | The team ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Ok. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/delete-automation-actions-runner # Delete an Automation Action runner `DELETE https://api.pagerduty.com/automation_actions/runners/{id}` Delete an Automation Action runner ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/delete-automation-actions-runner-team-association # Disassociate a runner from a team `DELETE https://api.pagerduty.com/automation_actions/runners/{id}/teams/{team_id}` Disassociates a runner from a team ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `team_id` | string | yes | The team ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Ok. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-all-automation-actions # List Automation Actions `GET https://api.pagerduty.com/automation_actions/actions` Lists Automation Actions matching provided query params. The returned records are sorted by action name in alphabetical order. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `name` | string | | Filters results to include the ones matching the name (case insensitive substring matching) | | `runner_id` | string | | Filters results to include the ones linked to the specified runner. Specifying the value `any` filters results to include the ones linked to runners only, thus omitting the results not linked to runners. | | `classification` | string \| null | | Filters results to include the ones matching the specified classification (aka category) One of: `diagnostic`, `remediation`. | | `team_id` | string | | Filters results to include the ones associated with the specified team. | | `service_id` | string | | Filters results to include the ones associated with the specified service. | | `action_type` | string | | Filters results to include the ones matching the specified action type. One of: `script`, `process_automation`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of actions ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `actions` | array of one of: object \| object | yes | | | `actions[].id` | string | yes | (option 1) Read-only. | | `actions[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].type` | string | yes | (option 1) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `actions[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `actions[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].name` | string | yes | (option 1) | | `actions[].description` | string | | (option 1) | | `actions[].action_type` | string | yes | (option 1) One of: `script`, `process_automation`. | | `actions[].action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `actions[].runner` | string | | (option 1) Max length: 36. | | `actions[].runner_type` | string | | (option 1) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `actions[].services` | array of object | | (option 1) | | `actions[].services[].id` | string | yes | Read-only. | | `actions[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].services[].type` | string | yes | One of: `service_reference`. | | `actions[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `actions[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].privileges` | object | | (option 1) | | `actions[].privileges.permissions` | array of string | yes | | | `actions[].metadata` | object | | (option 1) | | `actions[].creation_time` | string (date-time) | yes | (option 1) The date/time. | | `actions[].modify_time` | string (date-time) | yes | (option 1) The date/time. | | `actions[].last_run` | string (date-time) | | (option 1) The date/time. | | `actions[].last_run_by` | one of: object \| object \| object | | (option 1) | | `actions[].last_run_by.id` | string | yes | (option 1) Read-only. | | `actions[].last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `actions[].last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `actions[].last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].last_run_by.id` | string | yes | (option 2) | | `actions[].last_run_by.type` | string | yes | (option 2) | | `actions[].last_run_by.id` | string | yes | (option 3) Read-only. | | `actions[].last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `actions[].last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `actions[].last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `actions[].allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `actions[].allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `actions[].map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `actions[].action_data_reference` | object | yes | (option 1) | | `actions[].action_data_reference.script` | string | yes | Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `actions[].action_data_reference.invocation_command` | string | | The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `actions[].id` | string | yes | (option 2) Read-only. | | `actions[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].type` | string | yes | (option 2) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `actions[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `actions[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].name` | string | yes | (option 2) | | `actions[].description` | string | | (option 2) | | `actions[].action_type` | string | yes | (option 2) One of: `script`, `process_automation`. | | `actions[].action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `actions[].runner` | string | | (option 2) Max length: 36. | | `actions[].runner_type` | string | | (option 2) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `actions[].services` | array of object | | (option 2) | | `actions[].services[].id` | string | yes | Read-only. | | `actions[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].services[].type` | string | yes | One of: `service_reference`. | | `actions[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `actions[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].privileges` | object | | (option 2) Same fields as `actions[].privileges` above. | | `actions[].metadata` | object | | (option 2) | | `actions[].creation_time` | string (date-time) | yes | (option 2) The date/time. | | `actions[].modify_time` | string (date-time) | yes | (option 2) The date/time. | | `actions[].last_run` | string (date-time) | | (option 2) The date/time. | | `actions[].last_run_by` | one of: object \| object \| object | | (option 2) | | `actions[].last_run_by.id` | string | yes | (option 1) Read-only. | | `actions[].last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `actions[].last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `actions[].last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].last_run_by.id` | string | yes | (option 2) | | `actions[].last_run_by.type` | string | yes | (option 2) | | `actions[].last_run_by.id` | string | yes | (option 3) Read-only. | | `actions[].last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `actions[].last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `actions[].last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `actions[].allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `actions[].allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `actions[].map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `actions[].action_data_reference` | object | yes | (option 2) | | `actions[].action_data_reference.process_automation_job_id` | string | yes | Max length: 36. | | `actions[].action_data_reference.process_automation_job_arguments` | string | | Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `actions[].action_data_reference.process_automation_node_filter` | string | | Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | | `privileges` | object | | Same fields as `actions[].privileges` above. | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "actions": [ { "action_data_reference": { "script": "java --version" }, "action_type": "script", "type": "action", "creation_time": "2022-11-08T14:54:02.267989Z", "description": "Restarts apache on the us-west-2-shopping-cart host", "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "modify_time": "2022-11-08T14:54:02.267989Z", "name": "Restart apache", "only_invocable_on_unresolved_incidents": false, "map_to_all_services": false, "allow_invocation_manually": true, "allow_invocation_from_event_orchestration": true, "privileges": { "permissions": [ "read", "update", "delete", "invoke" ] }, "services": [ { "id": "PRDRWUJ", "type": "service_reference" } ] }, { "action_data_reference": { "script": "java --version" }, "action_type": "script", "type": "action", "creation_time": "2022-11-08T14:54:02.267989Z", "description": "Restarts apache on the us-west-2-shopping-cart host", "id": "01DACKMP6Q3Y5YG51ENA26CX2I", "modify_time": "2022-11-08T14:54:02.267989Z", "name": "Restart apache", "only_invocable_on_unresolved_incidents": false, "map_to_all_services": false, "allow_invocation_manually": true, "allow_invocation_from_event_orchestration": true, "privileges": { "permissions": [ "read", "update" ] } } ], "limit": 2, "next_cursor": null, "privileges": { "permissions": [ "read", "update" ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-action # Get an Automation Action `GET https://api.pagerduty.com/automation_actions/actions/{id}` Get an Automation Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Action information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `action` | one of: object \| object | yes | | | `action.id` | string | yes | (option 1) Read-only. | | `action.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 1) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 1) | | `action.description` | string | | (option 1) | | `action.action_type` | string | yes | (option 1) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 1) Max length: 36. | | `action.runner_type` | string | | (option 1) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 1) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 1) | | `action.privileges.permissions` | array of string | yes | | | `action.metadata` | object | | (option 1) | | `action.creation_time` | string (date-time) | yes | (option 1) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 1) The date/time. | | `action.last_run` | string (date-time) | | (option 1) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 1) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 1) | | `action.action_data_reference.script` | string | yes | Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `action.action_data_reference.invocation_command` | string | | The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `action.teams` | array of object | | (option 1) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.id` | string | yes | (option 2) Read-only. | | `action.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 2) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 2) | | `action.description` | string | | (option 2) | | `action.action_type` | string | yes | (option 2) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 2) Max length: 36. | | `action.runner_type` | string | | (option 2) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 2) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 2) Same fields as `action.privileges` above. | | `action.metadata` | object | | (option 2) | | `action.creation_time` | string (date-time) | yes | (option 2) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 2) The date/time. | | `action.last_run` | string (date-time) | | (option 2) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 2) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 2) | | `action.action_data_reference.process_automation_job_id` | string | yes | Max length: 36. | | `action.action_data_reference.process_automation_job_arguments` | string | | Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `action.action_data_reference.process_automation_node_filter` | string | | Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | | `action.teams` | array of object | | (option 2) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "action": { "action_data_reference": { "script": "java --version" }, "action_type": "script", "type": "action", "creation_time": "2022-11-08T14:54:02.267989Z", "description": "Restarts apache on the us-west-2-shopping-cart host", "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "modify_time": "2022-11-08T14:54:02.267989Z", "name": "Restart apache", "only_invocable_on_unresolved_incidents": false, "allow_invocation_manually": true, "allow_invocation_from_event_orchestration": true, "map_to_all_services": false, "privileges": { "permissions": [ "read", "update", "delete", "invoke" ] }, "services": [ { "id": "PRDRWUJ", "type": "service_reference" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-action-service-association # Get the details of an Automation Action / service relation `GET https://api.pagerduty.com/automation_actions/actions/{id}/services/{service_id}` Gets the details of a Automation Action / service relation ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Service reference ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | | | | `service.id` | string | yes | Read-only. | | `service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.type` | string | yes | One of: `service_reference`. | | `service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "service": { "id": "PQ9K7I8", "type": "service_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-action-service-associations # Get all service references associated with an Automation Action `GET https://api.pagerduty.com/automation_actions/actions/{id}/services` Gets all service references associated with an Automation Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of service references ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `services` | array of object | | | | `services[].id` | string | yes | Read-only. | | `services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].type` | string | yes | One of: `service_reference`. | | `services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "services": [ { "id": "PQ9K7I8", "type": "service_reference" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-action-team-association # Get the details of an Automation Action / team relation `GET https://api.pagerduty.com/automation_actions/actions/{id}/teams/{team_id}` Gets the details of an Automation Action / team relation ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `team_id` | string | yes | The team ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | | | | `team.id` | string | yes | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | One of: `team_reference`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-action-team-associations # Get all team references associated with an Automation Action `GET https://api.pagerduty.com/automation_actions/actions/{id}/teams` Gets all team references associated with an Automation Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `teams` | array of object | | | | `teams[].id` | string | yes | Read-only. | | `teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `teams[].type` | string | yes | One of: `team_reference`. | | `teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-invocation # Get an Invocation `GET https://api.pagerduty.com/automation_actions/invocations/{id}` Get an Automation Action Invocation ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Invocation information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `invocation` | object | yes | | | `invocation.id` | string | yes | Read-only. | | `invocation.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `invocation.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocation.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.action_snapshot` | object | yes | | | `invocation.action_snapshot.name` | string | yes | | | `invocation.action_snapshot.action_type` | string | yes | One of: `script`, `process_automation`. | | `invocation.action_snapshot.action_data_reference` | one of: object \| object | | | | `invocation.action_snapshot.action_data_reference.process_automation_job_id` | string | yes | (option 1) Max length: 36. | | `invocation.action_snapshot.action_data_reference.process_automation_job_arguments` | string | | (option 1) Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `invocation.action_snapshot.action_data_reference.process_automation_node_filter` | string | | (option 1) Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | | `invocation.action_snapshot.action_data_reference.script` | string | yes | (option 2) Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `invocation.action_snapshot.action_data_reference.invocation_command` | string | | (option 2) The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `invocation.runner_id` | string | yes | | | `invocation.timing` | array of object | yes | A list of state transitions with timestamps, sorted in ascending order by timestamp. Only the 'created' transition is guaranteed to exist at any time. | | `invocation.timing[].timestamp` | string (date-time) | yes | The date/time. | | `invocation.timing[].state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocation.duration` | integer | | The duration of the invocation's execution time. | | `invocation.state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocation.action_id` | string | yes | | | `invocation.metadata` | object | yes | | | `invocation.metadata.agent` | one of: object \| object \| object \| object | yes | | | `invocation.metadata.agent.id` | string | yes | (option 1) Read-only. | | `invocation.metadata.agent.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.agent.type` | string | yes | (option 1) One of: `user_reference`. | | `invocation.metadata.agent.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.agent.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.metadata.agent.id` | string | yes | (option 2) | | `invocation.metadata.agent.type` | string | yes | (option 2) | | `invocation.metadata.agent.id` | string | yes | (option 3) Read-only. | | `invocation.metadata.agent.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.agent.type` | string | yes | (option 3) One of: `account_reference`. | | `invocation.metadata.agent.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.agent.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocation.metadata.agent.id` | string | yes | (option 4) | | `invocation.metadata.agent.type` | string | yes | (option 4) | | `invocation.metadata.incident` | object | | | | `invocation.metadata.incident.id` | string | yes | Read-only. | | `invocation.metadata.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocation.metadata.incident.type` | string | yes | One of: `incident_reference`. | | `invocation.metadata.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocation.metadata.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "invocation": { "id": "01DBYD4A25RCXAXQDC9ZX0678V", "type": "invocation", "action_id": "01DAW70HK24JZORNE0P9C2V1L9", "action_snapshot": { "name": "Restart Apache", "action_type": "process_automation", "action_data_reference": { "process_automation_job_arguments": "prod-datapipe", "process_automation_node_filter": "mynode1 !nodename: mynode2", "process_automation_job_id": "79c199bba1aff6e519f198457f5ec0fc" } }, "duration": 5, "metadata": { "agent": { "id": "PRJ94S1", "type": "user_reference" }, "incident": { "id": "Q2LAR4ADCXC8IB", "type": "incident_reference" } }, "runner_id": "01COQFFNVWIONSLY8C66YTU2O5", "state": "completed", "timing": [ { "creation_timestamp": "2022-11-08T06:30:05.018949Z", "state": "created" }, { "creation_timestamp": "2022-11-08T06:30:10.069000Z", "state": "running" }, { "creation_timestamp": "2022-11-08T06:30:10.083000Z", "state": "completed" }, { "creation_timestamp": "2022-11-08T06:30:10.066000Z", "state": "queued" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-runner # Get an Automation Action runner `GET https://api.pagerduty.com/automation_actions/runners/{id}` Get an Automation Action runner ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Runner information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `runner` | object | yes | | | `runner.id` | string | yes | Read-only. | | `runner.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `runner.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.runner_type` | string | yes | sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runner.name` | string | yes | | | `runner.description` | string | | | | `runner.last_seen` | string (date-time) | | | | `runner.status` | string | yes | Configured -- Runner has connected to the backend at least once NotConfigured -- Runner has never connected to backend. One of: `Configured`, `NotConfigured`. | | `runner.creation_time` | string (date-time) | yes | | | `runner.runbook_base_uri` | string | | The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runner.teams` | array of object | | The list of teams associated with the Runner. Read-only. | | `runner.teams[].id` | string | yes | Read-only. | | `runner.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.teams[].type` | string | yes | One of: `team_reference`. | | `runner.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.privileges` | object | | | | `runner.privileges.permissions` | array of string | yes | | | `runner.associated_actions` | object | | References to at most 3 actions associated with the Runner. Use appropriate endpoints to retrieve the full list of associated actions. | | `runner.associated_actions.actions` | array of object | yes | | | `runner.associated_actions.actions[].id` | string | yes | Read-only. | | `runner.associated_actions.actions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.associated_actions.actions[].type` | string | yes | One of: `action_reference`. | | `runner.associated_actions.actions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.associated_actions.actions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.associated_actions.more` | boolean | yes | Indicates whether more actions exist for the Runner. | | `runner.metadata` | object | | Additional metadata. | Example: Response Example ```json { "runner": { "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "name": "us-west-2 prod sidecar runner", "summary": "us-west-2 prod sidecar runner", "type": "runner", "description": "us-west-2 prod sidecar runner provisioned by SRE", "creation_time": "2022-10-21T19:42:52.127369Z", "runner_type": "sidecar", "status": "Configured", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "privileges": { "permissions": [ "read", "update" ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-runner-team-association # Get the details of a runner / team relation `GET https://api.pagerduty.com/automation_actions/runners/{id}/teams/{team_id}` Gets the details of a runner / team relation ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `team_id` | string | yes | The team ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | | | | `team.id` | string | yes | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | One of: `team_reference`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "team": { "id": "PQ9K7I8", "type": "team_reference" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-runner-team-associations # Get all team references associated with a runner `GET https://api.pagerduty.com/automation_actions/runners/{id}/teams` Gets all team references associated with a runner ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `teams` | array of object | | | | `teams[].id` | string | yes | Read-only. | | `teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `teams[].type` | string | yes | One of: `team_reference`. | | `teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/get-automation-actions-runners # List Automation Action runners `GET https://api.pagerduty.com/automation_actions/runners` Lists Automation Action runners matching provided query params. The returned records are sorted by runner name in alphabetical order. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `name` | string | | Filters results to include the ones matching the name (case insensitive substring matching) | | `include[]` | array of string | | Includes additional data elements into the response. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Runners matching the criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `runners` | array of object | | | | `runners[].id` | string | yes | Read-only. | | `runners[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runners[].type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `runners[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runners[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runners[].runner_type` | string | yes | sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runners[].name` | string | yes | | | `runners[].description` | string | | | | `runners[].last_seen` | string (date-time) | | | | `runners[].status` | string | yes | Configured -- Runner has connected to the backend at least once NotConfigured -- Runner has never connected to backend. One of: `Configured`, `NotConfigured`. | | `runners[].creation_time` | string (date-time) | yes | | | `runners[].runbook_base_uri` | string | | The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runners[].teams` | array of object | | The list of teams associated with the Runner. Read-only. | | `runners[].teams[].id` | string | yes | Read-only. | | `runners[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runners[].teams[].type` | string | yes | One of: `team_reference`. | | `runners[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runners[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runners[].privileges` | object | | | | `runners[].privileges.permissions` | array of string | yes | | | `runners[].associated_actions` | object | | References to at most 3 actions associated with the Runner. Use appropriate endpoints to retrieve the full list of associated actions. | | `runners[].associated_actions.actions` | array of object | yes | | | `runners[].associated_actions.actions[].id` | string | yes | Read-only. | | `runners[].associated_actions.actions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runners[].associated_actions.actions[].type` | string | yes | One of: `action_reference`. | | `runners[].associated_actions.actions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runners[].associated_actions.actions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runners[].associated_actions.more` | boolean | yes | Indicates whether more actions exist for the Runner. | | `runners[].metadata` | object | | Additional metadata. | | `privileges` | object | | Same fields as `runners[].privileges` above. | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "runners": [ { "id": "01DACKMP6Q3Y5YG51ENA26CX2I", "name": "us-west-2 prod runbook runner", "description": "us-west-2 prod runbook runner provisioned by SRE", "creation_time": "2022-10-21T19:42:52.127369Z", "type": "runner", "runner_type": "runbook", "runbook_base_uri": "acme.prod", "status": "Configured", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "privileges": { "permissions": [ "read", "update", "delete" ] } }, { "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "name": "us-west-2 prod sidecar runner", "description": "us-west-2 prod sidecar runner provisioned by SRE", "creation_time": "2022-10-21T19:42:52.127369Z", "type": "runner", "runner_type": "sidecar", "status": "Configured", "privileges": { "permissions": [ "read", "update" ] } } ], "privileges": { "permissions": [ "create" ] }, "limit": 2, "next_cursor": "eyJjMiI6IjAxREEyTUxZTjBKNUVGQzFMS1dYVUtEREtUIiwiYzEiOiJSQkEgU2hhcmVkIFN0YWdpbmcgSW5zdGFuY2UifQ==" } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/list-automation-action-invocations # List Invocations `GET https://api.pagerduty.com/automation_actions/invocations` List Invocations ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `invocation_state` | string | | Invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `not_invocation_state` | string | | Invocation state inverse filter (matches invocations NOT in the specified state) One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `incident_id` | string | | Incident ID. | | `action_id` | string | | Action ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Invocations matching the criteria ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `invocations` | array of object | yes | List of invocations sorted by creation_time in reverse chronological order (newest invocations first). At most 25 invocations are returned. | | `invocations[].id` | string | yes | Read-only. | | `invocations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocations[].type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `invocations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocations[].action_snapshot` | object | yes | | | `invocations[].action_snapshot.name` | string | yes | | | `invocations[].action_snapshot.action_type` | string | yes | One of: `script`, `process_automation`. | | `invocations[].action_snapshot.action_data_reference` | one of: object \| object | | | | `invocations[].action_snapshot.action_data_reference.process_automation_job_id` | string | yes | (option 1) Max length: 36. | | `invocations[].action_snapshot.action_data_reference.process_automation_job_arguments` | string | | (option 1) Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `invocations[].action_snapshot.action_data_reference.process_automation_node_filter` | string | | (option 1) Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | | `invocations[].action_snapshot.action_data_reference.script` | string | yes | (option 2) Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `invocations[].action_snapshot.action_data_reference.invocation_command` | string | | (option 2) The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `invocations[].runner_id` | string | yes | | | `invocations[].timing` | array of object | yes | A list of state transitions with timestamps, sorted in ascending order by timestamp. Only the 'created' transition is guaranteed to exist at any time. | | `invocations[].timing[].timestamp` | string (date-time) | yes | The date/time. | | `invocations[].timing[].state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocations[].duration` | integer | | The duration of the invocation's execution time. | | `invocations[].state` | string | yes | prepared -- the invocation exists and can be referenced, but is NOT available to a Runner
created -- the invocation exists and is waiting for a Runner
sent -- invocation sent to a Runner
queued -- invocation queued by a Runner
running -- invocation is being ran by a Runner
aborted -- invocation was aborted on a Runner
completed -- invocation completed on a Runner
error -- invocation encountered an error on a Runner unknown -- transient error encountered when fetching invocation state. One of: `prepared`, `created`, `sent`, `queued`, `running`, `aborted`, `completed`, `error`, `unknown`. | | `invocations[].action_id` | string | yes | | | `invocations[].metadata` | object | yes | | | `invocations[].metadata.agent` | one of: object \| object \| object \| object | yes | | | `invocations[].metadata.agent.id` | string | yes | (option 1) Read-only. | | `invocations[].metadata.agent.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocations[].metadata.agent.type` | string | yes | (option 1) One of: `user_reference`. | | `invocations[].metadata.agent.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `invocations[].metadata.agent.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocations[].metadata.agent.id` | string | yes | (option 2) | | `invocations[].metadata.agent.type` | string | yes | (option 2) | | `invocations[].metadata.agent.id` | string | yes | (option 3) Read-only. | | `invocations[].metadata.agent.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocations[].metadata.agent.type` | string | yes | (option 3) One of: `account_reference`. | | `invocations[].metadata.agent.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `invocations[].metadata.agent.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `invocations[].metadata.agent.id` | string | yes | (option 4) | | `invocations[].metadata.agent.type` | string | yes | (option 4) | | `invocations[].metadata.incident` | object | | | | `invocations[].metadata.incident.id` | string | yes | Read-only. | | `invocations[].metadata.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `invocations[].metadata.incident.type` | string | yes | One of: `incident_reference`. | | `invocations[].metadata.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `invocations[].metadata.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "invocations": [ { "id": "01DBYD4A25RCXAXQDC9ZX0678V", "type": "invocation", "action_id": "01DAW70HK24JZORNE0P9C2V1L9", "action_snapshot": { "name": "Restart Apache", "action_type": "process_automation", "action_data_reference": { "process_automation_job_arguments": "prod-datapipe", "process_automation_node_filter": "mynode1 !nodename: mynode2", "process_automation_job_id": "79c199bba1aff6e519f198457f5ec0fc" } }, "duration": 5, "metadata": { "agent": { "id": "PRJ94S1", "type": "user_reference" }, "incident": { "id": "Q2LAR4ADCXC8IB", "type": "incident_reference" } }, "runner_id": "01COQFFNVWIONSLY8C66YTU2O5", "state": "completed", "timing": [ { "creation_timestamp": "2022-11-08T06:30:05.018949Z", "state": "created" }, { "creation_timestamp": "2022-11-08T06:30:10.069000Z", "state": "running" }, { "creation_timestamp": "2022-11-08T06:30:10.083000Z", "state": "completed" }, { "creation_timestamp": "2022-11-08T06:30:10.066000Z", "state": "queued" } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/update-automation-action # Update an Automation Action `PUT https://api.pagerduty.com/automation_actions/actions/{id}` Updates an Automation Action ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `action` | one of: object \| object | yes | | | `action.name` | string | | (option 1) Max length: 255. | | `action.description` | string | | (option 1) Max length: 1024. | | `action.action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `action.action_type` | string | | (option 1) One of: `script`, `process_automation`. | | `action.runner` | string | | (option 1) Max length: 36. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | | (option 1) | | `action.action_data_reference.script` | string | yes | Body of the script to be executed on the Runner. To execute it, the Runner will write the content of the property into a temp file, make the file executable and execute it. It is assumed that the Runner has a properly configured environment to run the script as an executable file. This behaviour can be altered by providing the `invocation_command` property. The maxLength value is specified in bytes. Max length: 16777215. | | `action.action_data_reference.invocation_command` | string | | The command to executed a script with. With the body of the script written into a temp file, the Runner will execute the ` ` command. The maxLength value is specified in bytes. Max length: 65535. | | `action.name` | string | | (option 2) Max length: 255. | | `action.description` | string | | (option 2) Max length: 1024. | | `action.action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `action.action_type` | string | | (option 2) One of: `script`, `process_automation`. | | `action.runner` | string | | (option 2) Max length: 36. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | | (option 2) | | `action.action_data_reference.process_automation_job_id` | string | yes | Max length: 36. | | `action.action_data_reference.process_automation_job_arguments` | string | | Arguments to pass to the Process Automation job. The maxLength value is specified in bytes. Max length: 1024. | | `action.action_data_reference.process_automation_node_filter` | string | | Node filter for the Process Automation job. The maxLength value is specified in bytes. Filter syntax: https://docs.rundeck.com/docs/manual/11-node-filters.html#node-filter-syntax. Max length: 1024. | ## Response 200 Action information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `action` | one of: object \| object | yes | | | `action.id` | string | yes | (option 1) Read-only. | | `action.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 1) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 1) | | `action.description` | string | | (option 1) | | `action.action_type` | string | yes | (option 1) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 1) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 1) Max length: 36. | | `action.runner_type` | string | | (option 1) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 1) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 1) | | `action.privileges.permissions` | array of string | yes | | | `action.metadata` | object | | (option 1) | | `action.creation_time` | string (date-time) | yes | (option 1) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 1) The date/time. | | `action.last_run` | string (date-time) | | (option 1) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 1) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 1) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 1) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 1) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 1) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 1) Same fields as `action.action_data_reference` above. | | `action.teams` | array of object | | (option 1) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.id` | string | yes | (option 2) Read-only. | | `action.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | yes | (option 2) A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `action.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.name` | string | yes | (option 2) | | `action.description` | string | | (option 2) | | `action.action_type` | string | yes | (option 2) One of: `script`, `process_automation`. | | `action.action_classification` | string \| null | | (option 2) One of: `diagnostic`, `remediation`. | | `action.runner` | string | | (option 2) Max length: 36. | | `action.runner_type` | string | | (option 2) sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `action.services` | array of object | | (option 2) | | `action.services[].id` | string | yes | Read-only. | | `action.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.services[].type` | string | yes | One of: `service_reference`. | | `action.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.privileges` | object | | (option 2) Same fields as `action.privileges` above. | | `action.metadata` | object | | (option 2) | | `action.creation_time` | string (date-time) | yes | (option 2) The date/time. | | `action.modify_time` | string (date-time) | yes | (option 2) The date/time. | | `action.last_run` | string (date-time) | | (option 2) The date/time. | | `action.last_run_by` | one of: object \| object \| object | | (option 2) | | `action.last_run_by.id` | string | yes | (option 1) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 1) One of: `user_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.last_run_by.id` | string | yes | (option 2) | | `action.last_run_by.type` | string | yes | (option 2) | | `action.last_run_by.id` | string | yes | (option 3) Read-only. | | `action.last_run_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.last_run_by.type` | string | yes | (option 3) One of: `account_reference`. | | `action.last_run_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `action.last_run_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.only_invocable_on_unresolved_incidents` | boolean | | (option 2) If true, the action can only be invoked against an unresolved incident. Default: `false`. | | `action.allow_invocation_manually` | boolean | | (option 2) If true, the action can only be invoked manually by a user. Default: `true`. | | `action.allow_invocation_from_event_orchestration` | boolean | | (option 2) If true, the action can only be invoked automatically by an Event Orchestration. Default: `true`. | | `action.map_to_all_services` | boolean | | (option 2) If true, the action will be associated with every service. Default: `false`. | | `action.action_data_reference` | object | yes | (option 2) Same fields as `action.action_data_reference` above. | | `action.teams` | array of object | | (option 2) | | `action.teams[].id` | string | yes | Read-only. | | `action.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.teams[].type` | string | yes | One of: `team_reference`. | | `action.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: response ```json { "action": { "action_data_reference": { "script": "java --version" }, "action_type": "script", "type": "action", "creation_time": "2022-11-08T14:54:02.267989Z", "description": "Restarts apache on the us-west-2-shopping-cart host", "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "modify_time": "2022-11-08T14:54:02.267989Z", "name": "Restart apache", "only_invocable_on_unresolved_incidents": false, "allow_invocation_manually": true, "allow_invocation_from_event_orchestration": true, "map_to_all_services": false, "privileges": { "permissions": [ "read", "update", "delete", "invoke" ] }, "services": [ { "id": "PRDRWUJ", "type": "service_reference" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/automation-actions/update-automation-actions-runner # Update an Automation Action runner `PUT https://api.pagerduty.com/automation_actions/runners/{id}` Update an Automation Action runner ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `runner` | one of: object \| object | yes | | | `runner.name` | string | | (RunnerSidecarBody) Max length: 255. | | `runner.description` | string | | (RunnerSidecarBody) Max length: 1024. | | `runner.name` | string | | (RunnerRunbookBody) Max length: 255. | | `runner.description` | string | | (RunnerRunbookBody) Max length: 1024. | | `runner.runbook_base_uri` | string | | (RunnerRunbookBody) The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runner.runbook_api_key` | string | | (RunnerRunbookBody) The API key to connect to the Runbook server with. If omitted, the previously stored value will remain unchanged. Max length: 64. | Example: request ```json { "runner": { "name": "us-west-2 prod sidecar runner", "description": "us-west-2 prod sidecar runner provisioned by SRE" } } ``` ## Response 200 Runner information ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `runner` | object | yes | | | `runner.id` | string | yes | Read-only. | | `runner.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `runner.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.runner_type` | string | yes | sidecar -- The runner is backed by an external sidecar that polls for invocations. runbook -- The runner communicates directly with a runbook instance. One of: `sidecar`, `runbook`. | | `runner.name` | string | yes | | | `runner.description` | string | | | | `runner.last_seen` | string (date-time) | | | | `runner.status` | string | yes | Configured -- Runner has connected to the backend at least once NotConfigured -- Runner has never connected to backend. One of: `Configured`, `NotConfigured`. | | `runner.creation_time` | string (date-time) | yes | | | `runner.runbook_base_uri` | string | | The base URI of the Runbook server to connect to. May only contain alphanumeric characters, periods, underscores and dashes. Specified as the subdomain portion of an RBA host, as in .runbook.pagerduty.cloud. Max length: 255. | | `runner.teams` | array of object | | The list of teams associated with the Runner. Read-only. | | `runner.teams[].id` | string | yes | Read-only. | | `runner.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.teams[].type` | string | yes | One of: `team_reference`. | | `runner.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.privileges` | object | | | | `runner.privileges.permissions` | array of string | yes | | | `runner.associated_actions` | object | | References to at most 3 actions associated with the Runner. Use appropriate endpoints to retrieve the full list of associated actions. | | `runner.associated_actions.actions` | array of object | yes | | | `runner.associated_actions.actions[].id` | string | yes | Read-only. | | `runner.associated_actions.actions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `runner.associated_actions.actions[].type` | string | yes | One of: `action_reference`. | | `runner.associated_actions.actions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `runner.associated_actions.actions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `runner.associated_actions.more` | boolean | yes | Indicates whether more actions exist for the Runner. | | `runner.metadata` | object | | Additional metadata. | Example: Response Example ```json { "runner": { "id": "01DA2MLYN0J5EFC1LKWXUKDDKT", "name": "us-west-2 prod sidecar runner", "summary": "us-west-2 prod sidecar runner", "type": "runner", "description": "us-west-2 prod sidecar runner provisioned by SRE", "creation_time": "2022-10-21T19:42:52.127369Z", "runner_type": "sidecar", "status": "Configured", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "privileges": { "permissions": [ "read", "update" ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/create-business-service # Create a Business Service `POST https://api.pagerduty.com/business_services` Create a new Business Service. Business services model capabilities that span multiple technical services and that may be owned by several different teams. There is a limit of 5,000 business services per account. If the limit is reached, the API will respond with an error. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `business_service` | object | | The Business Service to be created. | | `business_service.name` | string | | The name of the Business Service. | | `business_service.description` | string | | The description of the Business Service. | | `business_service.point_of_contact` | string | | The owner of the Business Service. | | `business_service.team` | object | | Reference to the team that owns the Business Service. | | `business_service.team.id` | string | | The Team ID. | Example: Request Example ```json { "business_service": { "name": "Self-serve mobile checkout", "description": "Checkout service for our mobile clients", "point_of_contact": "PagerDuty Admin", "team": { "id": "P3ZQXDF" } } } ``` ## Response 200 The Business Service that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `business_service` | object | yes | | | `business_service.id` | string | | Read-only. | | `business_service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `business_service.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `business_service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `business_service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `business_service.name` | string | | The name of the business service. | | `business_service.description` | string | | The user-provided description of the business service. | | `business_service.point_of_contact` | string | | The point of contact assigned to this service. | | `business_service.team` | object \| null | | Reference to the team that owns the business service. | | `business_service.team.id` | string | yes | | | `business_service.team.type` | string | | A string that determines the schema of the object. Read-only. | | `business_service.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "business_service": { "id": "P1L1YEE", "type": "business_service", "self": "https://api.pagerduty.com/business_services/P1L1YEE", "html_url": null, "point_of_contact": "PagerDuty Admin", "name": "Self-serve mobile checkout", "description": "Checkout service for our mobile clients.", "summary": "Self-serve mobile checkout", "team": { "id": "P3ZQXDF", "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/create-business-service-account-subscription # Create Business Service Account Subscription `POST https://api.pagerduty.com/business_services/{id}/account_subscription` Subscribe your Account to a Business Service. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `account_is_subscribed` | boolean | yes | | Example: Response Example ```json { "account_is_subscribed": true } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/create-business-service-notification-subscribers # Create Business Service Subscribers `POST https://api.pagerduty.com/business_services/{id}/subscribers` Subscribe the given entities to the given Business Service. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to subscribe. | Field | Type | Required | Description | |---|---|---|---| | `subscribers` | array of object | yes | Min items: 1. Items must be unique. | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | Example: Request Example ```json { "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "team" }, { "subscriber_id": "PD1235", "subscriber_type": "team" }, { "subscriber_id": "PD1234", "subscriber_type": "user" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscriptions` | array of object | | | | `subscriptions[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].account_id` | string | | The type of the entity being subscribed to. | | `subscriptions[].result` | string | | The resulting status of the subscription. One of: `success`, `duplicate`, `unauthorized`. | Example: Response Example ```json { "subscriptions": [ { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "user", "result": "success" }, { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "duplicate" }, { "account_id": "PD1234", "subscribable_id": "PD1235", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "unauthorized" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/delete-business-service # Delete a Business Service `DELETE https://api.pagerduty.com/business_services/{id}` Delete an existing Business Service. Once the service is deleted, it will not be accessible from the web UI and new incidents won't be able to be created for this service. Business services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Business Service was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/delete-business-service-priority-thresholds # Deletes the account-level priority threshold for Business Service impact `DELETE https://api.pagerduty.com/business_services/priority_thresholds` Clears the Priority Threshold for the account. If the priority threshold is cleared, any Incident with a Priority set will be able to impact Business Services. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Priority Threshold for the account was successfully cleared. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service # Get a Business Service `GET https://api.pagerduty.com/business_services/{id}` Get details about an existing Business Service. Business services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The service business requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `business_service` | object | yes | | | `business_service.id` | string | | Read-only. | | `business_service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `business_service.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `business_service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `business_service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `business_service.name` | string | | The name of the business service. | | `business_service.description` | string | | The user-provided description of the business service. | | `business_service.point_of_contact` | string | | The point of contact assigned to this service. | | `business_service.team` | object \| null | | Reference to the team that owns the business service. | | `business_service.team.id` | string | yes | | | `business_service.team.type` | string | | A string that determines the schema of the object. Read-only. | | `business_service.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "business_service": { "id": "P1L1YEE", "type": "business_service", "self": "https://api.pagerduty.com/business_services/P1L1YEE", "html_url": null, "name": "Cross-tier business service", "description": "Business service affected by multiple teams", "point_of_contact": "PagerDuty Admin", "summary": "Cross-tier business services", "team": { "id": "PQ9K7I8", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PQ9K7I8" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service-impacts # List Business Services sorted by impacted status `GET https://api.pagerduty.com/business_services/impacts` Retrieve a list top-level Business Services sorted by highest Impact with `status` included. When called without the `ids[]` parameter, this endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted up to the limit of 200. The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name. To get impact information about a specific set of Business Services, use the `ids[]` parameter. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `additional_fields[]` | string | | Provides access to additional fields such as highest priority per business service and total impacted count. One of: `services.highest_impacting_priority`, `total_impacted_count`. | | `ids[]` | string | | The IDs of the resources. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `services` | array of object | | | | `services[].id` | string | | Read-only. | | `services[].name` | string | | Read-only. | | `services[].type` | string | | The kind of object that has been impacted. One of: `business_service`. | | `services[].status` | string | | The current impact status of the object. One of: `impacted`, `not_impacted`. | | `services[].additional_fields` | object | | | | `services[].additional_fields.highest_impacting_priority` | object \| null | | Priority information for the highest priority level that is affecting the impacted object. | | `services[].additional_fields.highest_impacting_priority.id` | string | | Read-only. | | `services[].additional_fields.highest_impacting_priority.order` | integer | | Read-only. | | `additional_fields` | object | | | | `additional_fields.total_impacted_count` | integer | | | Example: Response Example ```json { "limit": 100, "more": false, "services": [ { "id": "PD1234", "name": "Web API", "type": "business_service", "status": "impacted", "additional_fields": { "highest_impacting_priority": { "id": "PQOMK4S", "order": 128 } } }, { "id": "PF9KMXH", "name": "Analytics Backend", "type": "business_service", "status": "not_impacted", "additional_fields": { "highest_impacting_priority": null } } ], "additional_fields": { "total_impacted_count": 1 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service-priority-thresholds # Get the global priority threshold for a Business Service to be considered impacted by an Incident `GET https://api.pagerduty.com/business_services/priority_thresholds` Retrieves the priority threshold information for an account. Currently, there is a `global_threshold` that can be set for the account. Incidents that have a priority meeting or exceeding this threshold will be considered impacting on any Business Service that depends on the Service to which the Incident belongs. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `global_threshold` | object \| null | | | | `global_threshold.id` | string | | | | `global_threshold.order` | integer | | | Example: Response Example ```json { "limit": 100, "more": false, "global_threshold": null, "type": "object", "properties": { "id": "string", "order": "integer" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service-subscribers # List Business Service Subscribers `GET https://api.pagerduty.com/business_services/{id}/subscribers` Retrieve a list of Notification Subscribers on the Business Service. > Users must be added through `POST /business_services/{id}/subscribers` to be returned from this endpoint. Scoped OAuth requires: `subscribers.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `subscribers` | array of object | | | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `account_id` | string | | The ID of the account belonging to the subscriber entity. | Example: Response Example ```json { "limit": 100, "more": false, "offset": 0, "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "user" }, { "subscriber_id": "PD1234", "subscriber_type": "team" } ], "account_id": "PD1234", "total": 2 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service-supporting-service-impacts # List the supporting Business Services for the given Business Service Id, sorted by impacted status. `GET https://api.pagerduty.com/business_services/{id}/supporting_services/impacts` Retrieve of Business Services that support the given Business Service sorted by highest Impact with `status` included. This endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted up to the limit of 200. The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name. To get impact information about a specific set of Business Services, use the `ids[]` parameter on the `/business_services/impacts` endpoint. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `additional_fields[]` | string | | Provides access to additional fields such as highest priority per business service and total impacted count. One of: `services.highest_impacting_priority`, `total_impacted_count`. | | `ids[]` | string | | The IDs of the resources. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `services` | array of object | | | | `services[].id` | string | | Read-only. | | `services[].name` | string | | Read-only. | | `services[].type` | string | | The kind of object that has been impacted. One of: `business_service`. | | `services[].status` | string | | The current impact status of the object. One of: `impacted`, `not_impacted`. | | `services[].additional_fields` | object | | | | `services[].additional_fields.highest_impacting_priority` | object \| null | | Priority information for the highest priority level that is affecting the impacted object. | | `services[].additional_fields.highest_impacting_priority.id` | string | | Read-only. | | `services[].additional_fields.highest_impacting_priority.order` | integer | | Read-only. | | `additional_fields` | object | | | | `additional_fields.total_impacted_count` | integer | | | Example: Response Example ```json { "limit": 100, "more": false, "services": [ { "id": "PD1234", "name": "Web API", "type": "business_service", "status": "impacted", "additional_fields": { "highest_impacting_priority": { "id": "PQOMK4S", "order": 128 } } }, { "id": "PF9KMXH", "name": "Analytics Backend", "type": "business_service", "status": "not_impacted", "additional_fields": { "highest_impacting_priority": null } } ], "additional_fields": { "total_impacted_count": 1 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/get-business-service-top-level-impactors # List Impactors affecting Business Services `GET https://api.pagerduty.com/business_services/impactors` Retrieve a list of Impactors for the top-level Business Services on the account. Impactors are currently limited to Incidents. This endpoint does not return an exhaustive list of Impactors but rather provides access to the highest priority Impactors for the Business Services in question up to the limit of 200. To get Impactors for a specific set of Business Services, use the `ids[]` parameter. The returned Impactors are sorted first by priority and secondarily by their creation date. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `ids[]` | string | | The IDs of the resources. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `impactors` | array of object | | | | `impactors[].id` | string | | Read-only. | | `impactors[].type` | string | | The kind of object that is impacting. One of: `incident`. | Example: Response Example ```json { "limit": 100, "more": false, "impactors": [ { "id": "PD1234", "type": "incident" }, { "id": "PF9KMXH", "type": "incident" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/list-business-services # List Business Services `GET https://api.pagerduty.com/business_services` List existing Business Services. Business services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of services. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `business_services` | array of object | yes | | | `business_services[].id` | string | | Read-only. | | `business_services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `business_services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `business_services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `business_services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `business_services[].name` | string | | The name of the business service. | | `business_services[].description` | string | | The user-provided description of the business service. | | `business_services[].point_of_contact` | string | | The point of contact assigned to this service. | | `business_services[].team` | object \| null | | Reference to the team that owns the business service. | | `business_services[].team.id` | string | yes | | | `business_services[].team.type` | string | | A string that determines the schema of the object. Read-only. | | `business_services[].team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "business_services": [ { "type": "business_service", "self": "https://api.pagerduty.com/business_services/P3U7V58", "html_url": null, "point_of_contact": "PagerDuty Admin", "name": "stand-alone node", "team": null, "id": "P3U7V58", "description": "Very important business function", "summary": "stand-alone node" }, { "type": "business_service", "self": "https://api.pagerduty.com/business_services/P1L1YEE", "html_url": null, "point_of_contact": "PagerDuty Admin", "name": "Cross-tier business service", "id": "P1L1YEE", "summary": "Cross-tier business service", "team": { "id": "PQ9K7I8", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PQ9K7I8" } } ], "limit": 100, "offset": 0, "total": null, "more": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/put-business-service-priority-thresholds # Set the Account-level priority threshold for Business Service impact. `PUT https://api.pagerduty.com/business_services/priority_thresholds` Set the Account-level priority threshold for Business Service. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Set the `id` and `order` of the global Priority Threshold. These values can be obtained by calling the `/priorities` endpoint. Once set, Incidents must be at or above the specified level in order to impact Business Services. An exception to this rule is if the Incident has been added to the incident directly using the `PUT /incidents/{id}/business_services/{business_service_id}/impacts` endpoint. | Field | Type | Required | Description | |---|---|---|---| | `global_threshold` | object | yes | | | `global_threshold.id` | string | yes | Min length: 1. | | `global_threshold.order` | number | yes | | Example: example ```json { "global_threshold": { "id": "PTLNKGF", "order": 256 } } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `global_threshold` | object | yes | | | `global_threshold.id` | string | yes | | | `global_threshold.order` | number | yes | | Example: Response Example ```json { "global_threshold": { "id": "PTLNKGF", "order": 256 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/remove-business-service-account-subscription # Delete Business Service Account Subscription `DELETE https://api.pagerduty.com/business_services/{id}/account_subscription` Unsubscribe your Account from a Business Service. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The account was unsubscribed successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/remove-business-service-notification-subscriber # Remove Business Service Subscribers `POST https://api.pagerduty.com/business_services/{id}/unsubscribe` Unsubscribes the matching Subscribers from a Business Service. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to unsubscribe. | Field | Type | Required | Description | |---|---|---|---| | `subscribers` | array of object | yes | Min items: 1. Items must be unique. | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | Example: Request Example ```json { "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "team" }, { "subscriber_id": "PD1234", "subscriber_type": "user" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `deleted_count` | number | yes | | | `unauthorized_count` | number | yes | | | `non_existent_count` | number | yes | | Example: Response Example ```json { "deleted_count": 1, "unauthorized_count": 1, "non_existent_count": 0 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/business-services/update-business-service # Update a Business Service `PUT https://api.pagerduty.com/business_services/{id}` Update an existing Business Service. NOTE that this endpoint also accepts the PATCH verb. Business services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `business_service` | object | | The Business Service to be created. | | `business_service.name` | string | | The name of the Business Service. | | `business_service.description` | string | | The description of the Business Service. | | `business_service.point_of_contact` | string | | The owner of the Business Service. | | `business_service.team` | object | | Reference to the team that owns the Business Service. | | `business_service.team.id` | string | | The team ID. | Example: Request Example ```json { "business_service": { "name": "Self-serve mobile checkout", "description": "Checkout service for our mobile clients", "point_of_contact": "PagerDuty Admin", "team": { "id": "P3ZQXDF" } } } ``` ## Response 200 The Business Service that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `business_service` | object | yes | | | `business_service.id` | string | | Read-only. | | `business_service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `business_service.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `business_service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `business_service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `business_service.name` | string | | The name of the business service. | | `business_service.description` | string | | The user-provided description of the business service. | | `business_service.point_of_contact` | string | | The point of contact assigned to this service. | | `business_service.team` | object \| null | | Reference to the team that owns the business service. | | `business_service.team.id` | string | yes | | | `business_service.team.type` | string | | A string that determines the schema of the object. Read-only. | | `business_service.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "business_service": { "id": "P1L1YEE", "type": "business_service", "self": "https://api.pagerduty.com/business_services/P1L1YEE", "html_url": null, "point_of_contact": "PagerDuty Admin", "name": "Self-serve mobile checkout", "description": "Checkout service for our mobile clients.", "summary": "Self-serve mobile checkout", "team": { "id": "P3ZQXDF", "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/create-change-event # Create a Change Event `POST https://api.pagerduty.com/change_events` Sending Change Events is documented as part of the V2 Events API. See [`Send Change Event`](https://developer.pagerduty.com/api-reference/b3A6Mjc0ODI2Ng-send-change-events-to-the-pager-duty-events-api). ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 202 See [`Send Change Event`](https://developer.pagerduty.com/api-reference/b3A6Mjc0ODI2Ng-send-change-events-to-the-pager-duty-events-api) in the V2 Events API reference. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/get-change-event # Get a Change Event `GET https://api.pagerduty.com/change_events/{id}` Get details about an existing Change Event. Scoped OAuth requires: `change_events.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Change Event requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `change_event` | object | | | | `change_event.id` | string | | Read-only. | | `change_event.summary` | string | | A brief text summary of the event. Displayed in PagerDuty to provide information about the change. The maximum permitted length of this property is 1024 characters. | | `change_event.type` | string | | The type of object being created. Read-only. One of: `change_event`. Default: `change_event`. | | `change_event.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. Read-only. | | `change_event.services` | array of object | | An array containing Service objects that this change event is associated with. Read-only. | | `change_event.services[].id` | string | yes | Read-only. | | `change_event.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_event.services[].type` | string | yes | One of: `service_reference`. | | `change_event.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.integration` | object | | | | `change_event.integration.id` | string | yes | Read-only. | | `change_event.integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_event.integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `change_event.integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.routing_key` | string | | This is the 32 character Integration Key for an Integration on a Service. The same Integration Key can be used for both alert and change events. Read-only. | | `change_event.source` | string | | The unique name of the location where the Change Event occurred. Read-only. | | `change_event.links` | array of object | | List of links to include. Read-only. | | `change_event.links[].href` | string | | | | `change_event.links[].text` | string | | | | `change_event.images` | array of object | | Read-only. | | `change_event.images[].src` | string | | | | `change_event.images[].href` | string | | | | `change_event.images[].alt` | string | | | | `change_event.custom_details` | object | | Additional details about the change event. | Example: Response Example ```json { "change_event": { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "timestamp": "2020-07-17T08:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/2", "text": "View more details in Acme!" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/list-change-events # List Change Events `GET https://api.pagerduty.com/change_events` List all of the existing Change Events. Scoped OAuth requires: `change_events.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `integration_ids[]` | array of string | | An array of integration IDs. Only results related to these integrations will be returned. Items must be unique. | | `since` | string (date-time) | | The start of the date range over which you want to search, as a UTC ISO 8601 datetime string. Will return an HTTP 400 for non-UTC datetimes. Pattern: `YYYY-MM-DDThh:mm:ssZ`. | | `until` | string (date-time) | | The end of the date range over which you want to search, as a UTC ISO 8601 datetime string. Will return an HTTP 400 for non-UTC datetimes. Pattern: `YYYY-MM-DDThh:mm:ssZ`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The array of Change Events returned by the query. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `change_events` | array of object | | | | `change_events[].id` | string | | Read-only. | | `change_events[].summary` | string | | A brief text summary of the event. Displayed in PagerDuty to provide information about the change. The maximum permitted length of this property is 1024 characters. | | `change_events[].type` | string | | The type of object being created. Read-only. One of: `change_event`. Default: `change_event`. | | `change_events[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. Read-only. | | `change_events[].services` | array of object | | An array containing Service objects that this change event is associated with. Read-only. | | `change_events[].services[].id` | string | yes | Read-only. | | `change_events[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].services[].type` | string | yes | One of: `service_reference`. | | `change_events[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].integration` | object | | | | `change_events[].integration.id` | string | yes | Read-only. | | `change_events[].integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `change_events[].integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].routing_key` | string | | This is the 32 character Integration Key for an Integration on a Service. The same Integration Key can be used for both alert and change events. Read-only. | | `change_events[].source` | string | | The unique name of the location where the Change Event occurred. Read-only. | | `change_events[].links` | array of object | | List of links to include. Read-only. | | `change_events[].links[].href` | string | | | | `change_events[].links[].text` | string | | | | `change_events[].images` | array of object | | Read-only. | | `change_events[].images[].src` | string | | | | `change_events[].images[].href` | string | | | | `change_events[].images[].alt` | string | | | | `change_events[].custom_details` | object | | Additional details about the change event. | Example: Response Example ```json { "change_events": [ { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "id": "01BBYA6PEVW6A852BUO6QYUE7O", "timestamp": "2020-07-17T08:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/2", "text": "View more details in Acme!" } ] }, { "summary": "Build Success - Increase snapshot create timeout to 15 seconds", "id": "01BBYA6PDIXPL8KO1HPIUL9CZN", "timestamp": "2020-07-17T07:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "1", "run_time": "1233s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/1", "text": "View more details in Acme!" } ] } ], "limit": null, "offset": null, "total": null, "more": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/list-incident-related-change-events # List related Change Events for an Incident `GET https://api.pagerduty.com/incidents/{id}/related_change_events` List related Change Events for an Incident, as well as the reason these changes are correlated with the incident. Change events represent service changes such as deploys, build completion, and configuration changes, providing information that is critical during incident triage or hypercare. For more information on change events, see [Change Events](https://support.pagerduty.com/docs/change-events). The Change Correlation feature provides incident responders with recent change events that are most relevant to that incident. Change Correlation informs the responder why a particular change event was surfaced and correlated to an incident based on three key factors which include time, related service, or intelligence (machine learning). Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The array of Change Events returned by the query. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `change_events` | array of object | | | | `change_events[].id` | string | | Read-only. | | `change_events[].summary` | string | | A brief text summary of the event. Displayed in PagerDuty to provide information about the change. The maximum permitted length of this property is 1024 characters. | | `change_events[].type` | string | | The type of object being created. Read-only. One of: `change_event`. Default: `change_event`. | | `change_events[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. Read-only. | | `change_events[].services` | array of object | | An array containing Service objects that this change event is associated with. Read-only. | | `change_events[].services[].id` | string | yes | Read-only. | | `change_events[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].services[].type` | string | yes | One of: `service_reference`. | | `change_events[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].integration` | object | | | | `change_events[].integration.id` | string | yes | Read-only. | | `change_events[].integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `change_events[].integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].routing_key` | string | | This is the 32 character Integration Key for an Integration on a Service. The same Integration Key can be used for both alert and change events. Read-only. | | `change_events[].source` | string | | The unique name of the location where the Change Event occurred. Read-only. | | `change_events[].links` | array of object | | List of links to include. Read-only. | | `change_events[].links[].href` | string | | | | `change_events[].links[].text` | string | | | | `change_events[].images` | array of object | | Read-only. | | `change_events[].images[].src` | string | | | | `change_events[].images[].href` | string | | | | `change_events[].images[].alt` | string | | | | `change_events[].custom_details` | object | | Additional details about the change event. | | `change_events[].correlation_reason` | object | | | | `change_events[].correlation_reason.reason` | string | | The reason a change event was determined to be related to the given incident. Read-only. One of: `most_recent`, `related_service`, `intelligent`. | Example: Response Example ```json { "change_events": [ { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "id": "01BBYA6PEVW6A852BUO6QYUE7O", "timestamp": "2020-07-17T08:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/2", "text": "View more details in Acme!" } ], "correlation_reason": { "reason": "most_recent" } }, { "summary": "Build Success - Increase snapshot create timeout to 15 seconds", "id": "01BBYA6PDIXPL8KO1HPIUL9CZN", "timestamp": "2020-07-17T07:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "1", "run_time": "1233s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/1", "text": "View more details in Acme!" } ], "correlation_reason": { "reason": "related_service" } } ], "limit": null, "offset": null, "total": null, "more": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/list-service-change-events # List Change Events for a service `GET https://api.pagerduty.com/services/{id}/change_events` List all of the existing Change Events for a service. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search, as a UTC ISO 8601 datetime string. Will return an HTTP 400 for non-UTC datetimes. Pattern: `YYYY-MM-DDThh:mm:ssZ`. | | `until` | string (date-time) | | The end of the date range over which you want to search, as a UTC ISO 8601 datetime string. Will return an HTTP 400 for non-UTC datetimes. Pattern: `YYYY-MM-DDThh:mm:ssZ`. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `integration_ids[]` | array of string | | An array of integration IDs. Only results related to these integrations will be returned. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The array of Change Events returned by the query. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `change_events` | array of object | | | | `change_events[].id` | string | | Read-only. | | `change_events[].summary` | string | | A brief text summary of the event. Displayed in PagerDuty to provide information about the change. The maximum permitted length of this property is 1024 characters. | | `change_events[].type` | string | | The type of object being created. Read-only. One of: `change_event`. Default: `change_event`. | | `change_events[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. Read-only. | | `change_events[].services` | array of object | | An array containing Service objects that this change event is associated with. Read-only. | | `change_events[].services[].id` | string | yes | Read-only. | | `change_events[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].services[].type` | string | yes | One of: `service_reference`. | | `change_events[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].integration` | object | | | | `change_events[].integration.id` | string | yes | Read-only. | | `change_events[].integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_events[].integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `change_events[].integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_events[].integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_events[].routing_key` | string | | This is the 32 character Integration Key for an Integration on a Service. The same Integration Key can be used for both alert and change events. Read-only. | | `change_events[].source` | string | | The unique name of the location where the Change Event occurred. Read-only. | | `change_events[].links` | array of object | | List of links to include. Read-only. | | `change_events[].links[].href` | string | | | | `change_events[].links[].text` | string | | | | `change_events[].images` | array of object | | Read-only. | | `change_events[].images[].src` | string | | | | `change_events[].images[].href` | string | | | | `change_events[].images[].alt` | string | | | | `change_events[].custom_details` | object | | Additional details about the change event. | Example: Response Example ```json { "change_events": [ { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "id": "01BBYA6PEVW6A852BUO6QYUE7O", "timestamp": "2020-07-17T08:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/2", "text": "View more details in Acme!" } ] }, { "summary": "Build Success - Increase snapshot create timeout to 15 seconds", "id": "01BBYA6PDIXPL8KO1HPIUL9CZN", "timestamp": "2020-07-17T07:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "1", "run_time": "1233s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/1", "text": "View more details in Acme!" } ] } ], "limit": null, "offset": null, "total": null, "more": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/change-events/update-change-event # Update a Change Event `PUT https://api.pagerduty.com/change_events/{id}` Update an existing Change Event Scoped OAuth requires: `change_events.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The Change Event to be updated. | Field | Type | Required | Description | |---|---|---|---| | `change_event` | object | yes | | | `change_event.id` | string | | Read-only. | | `change_event.summary` | string | | A brief text summary of the event. Displayed in PagerDuty to provide information about the change. The maximum permitted length of this property is 1024 characters. | | `change_event.type` | string | | The type of object being created. Read-only. One of: `change_event`. Default: `change_event`. | | `change_event.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.timestamp` | string (date-time) | | The time at which the emitting tool detected or generated the event. Read-only. | | `change_event.services` | array of object | | An array containing Service objects that this change event is associated with. Read-only. | | `change_event.services[].id` | string | yes | Read-only. | | `change_event.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_event.services[].type` | string | yes | One of: `service_reference`. | | `change_event.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.integration` | object | | | | `change_event.integration.id` | string | yes | Read-only. | | `change_event.integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `change_event.integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `change_event.integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `change_event.integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `change_event.routing_key` | string | | This is the 32 character Integration Key for an Integration on a Service. The same Integration Key can be used for both alert and change events. Read-only. | | `change_event.source` | string | | The unique name of the location where the Change Event occurred. Read-only. | | `change_event.links` | array of object | | List of links to include. Read-only. | | `change_event.links[].href` | string | | | | `change_event.links[].text` | string | | | | `change_event.images` | array of object | | Read-only. | | `change_event.images[].src` | string | | | | `change_event.images[].href` | string | | | | `change_event.images[].alt` | string | | | | `change_event.custom_details` | object | | Additional details about the change event. | Example: Request Example ```json { "change_event": { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "type": "change_event", "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" } } } ``` ## Response 200 The Change Event that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `change_event` | object | | Same fields as `change_event` above. | Example: Response Example ```json { "change_event": { "summary": "Build Success - Increase snapshot create timeout to 30 seconds", "timestamp": "2020-07-17T08:42:58Z", "type": "change_event", "source": "acme-build-pipeline-tool-default-i-9999", "integration": { "id": "PEYSGVF", "type": "inbound_integration_reference" }, "services": [ { "id": "PEYSGRV", "type": "service_reference" } ], "custom_details": { "build_state": "passed", "build_number": "2", "run_time": "1236s" }, "links": [ { "href": "https://acme.pagerduty.dev/build/2", "text": "View more details in Acme!" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/add-service-now-table # Add a CMDB table `POST https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables` Adds a new ServiceNow CMDB table configuration to an existing integration. An integration may contain at most 8 tables. New tables are created with `status: disabled`; enable synchronization separately once the configuration has been validated. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The CMDB table configuration to add to the integration. | Field | Type | Required | Description | |---|---|---|---| | `cmdb_table` | object | yes | | | `cmdb_table.display_name` | string | yes | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `cmdb_table.ci_table_name` | string | yes | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `cmdb_table.query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `cmdb_table.field_mappings` | array of object | yes | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be marked as query fields. Min items: 2. Max items: 20. | | `cmdb_table.field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `cmdb_table.field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `cmdb_table.field_mappings[].type` | string | | Set to `query` to use this mapping as a lookup key for matching incoming events to Configuration Items. Omit it for enrichment fields (the default). At most 3 mappings may be marked `query`, and at least one mapping must be left as an enrichment field. When no mapping is marked `query`, the `name` field is used as the query field automatically. Only `query` is accepted here — any other value is rejected. One of: `query`. | Example: Add a CMDB table ```json { "cmdb_table": { "display_name": "Windows Servers", "ci_table_name": "cmdb_ci_win_server", "query_filter": null, "field_mappings": [ { "servicenow_field": "name", "event_field": "source" }, { "servicenow_field": "category", "event_field": "category" }, { "servicenow_field": "fault_count", "event_field": "fault count" }, { "servicenow_field": "cost_cc", "event_field": "cost cc" } ] } } ``` ## Response 201 The CMDB table was added to the integration successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cmdb_table` | object | | | | `cmdb_table.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. Read-only. | | `cmdb_table.display_name` | string | | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `cmdb_table.ci_table_name` | string | | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `cmdb_table.query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `cmdb_table.field_mappings` | array of object | | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be designated as query fields. | | `cmdb_table.field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `cmdb_table.field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `cmdb_table.field_mappings[].type` | string | | Determines how the field is used during enrichment. `enriched` fields add contextual data to a matched event, while `query` fields are used to match incoming events to Configuration Items. When no mapping specifies a `type`, the field defaults to `enriched` and the `name` field is automatically used as the single query field. To match on a different field — or on more than one field — set `type: query` on those mappings; in that mode `name` is no longer used as a query field unless it is itself marked `query`. Up to 3 query fields may be configured, and when more than one is set an event must contain a matching value for every query field to be enriched (logical AND). At least one mapping must be an enriched field. In responses, a mapping's `type` is `query`, `enriched`, or `discriminator`. `discriminator` is assigned automatically to the `sys_id` field of `cmdb_rel_ci` relationship tables to distinguish relationship types; it appears in responses but cannot be set on requests. One of: `query`, `enriched`, `discriminator`. | | `cmdb_table.status` | string | | The current data synchronization status of the table. `disabled`: sync is not enabled (the default for newly created tables). `syncing`: an initial sync is in progress. `active`: sync is healthy and incremental updates are running. `error`: sync failed (check the credentials or table configuration). Read-only. One of: `disabled`, `syncing`, `active`, `error`. | | `cmdb_table.created_at` | string (date-time) | | The date/time the table configuration was created. Read-only. | | `cmdb_table.updated_at` | string (date-time) | | The date/time the table configuration was last updated. Read-only. | | `cmdb_table.deleted_at` | string \| null (date-time) | | The date/time the table configuration was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "cmdb_table": { "id": "01HV9TBLE2DEFGHIJKLMNOPQRS", "display_name": "Windows Servers", "ci_table_name": "cmdb_ci_win_server", "query_filter": null, "field_mappings": [ { "servicenow_field": "name", "event_field": "source", "type": "query" }, { "servicenow_field": "category", "event_field": "category", "type": "enriched" }, { "servicenow_field": "fault_count", "event_field": "fault count", "type": "enriched" }, { "servicenow_field": "cost_cc", "event_field": "cost cc", "type": "enriched" } ], "status": "disabled", "created_at": "2026-06-30T20:00:00Z", "updated_at": "2026-06-30T20:00:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/create-service-now-credentials # Create ServiceNow credentials `POST https://api.pagerduty.com/enrichment/integrations/servicenow/credentials` Creates the ServiceNow API credentials used to authenticate synchronization and test requests. Only one credential set is allowed per account, and it is shared across the account's ServiceNow integration. The password is never returned in responses. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The ServiceNow credentials to create. Only one credential set is allowed per account. | Field | Type | Required | Description | |---|---|---|---| | `credentials` | object | yes | | | `credentials.instance_endpoint` | string | yes | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `credentials.user` | string | yes | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `credentials.password` | string | yes | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | Example: Create ServiceNow credentials ```json { "credentials": { "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "password": "YOUR_SERVICENOW_PASSWORD" } } ``` ## Response 201 The ServiceNow credentials were created successfully. The password is never returned. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `credentials` | object | | | | `credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | Example: Example Response ```json { "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T18:20:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/create-service-now-integration # Create a ServiceNow integration `POST https://api.pagerduty.com/enrichment/integrations/servicenow` Creates a ServiceNow enrichment integration with one or more CMDB table configurations. Only one integration is allowed per account. Each CMDB table must define between 2 and 20 field mappings, and an integration may contain at most 8 tables. Credentials are managed separately through the credentials endpoints. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The ServiceNow enrichment integration to create. Credentials are added separately through the credentials endpoint. | Field | Type | Required | Description | |---|---|---|---| | `name` | string | yes | The name of the integration. Max length: 100. | | `description` | string | | An optional description of the integration. Max length: 500. | | `cmdb_tables` | array of object | yes | The ServiceNow CMDB table configurations. An integration must have between 1 and 8 tables. Min items: 1. Max items: 8. | | `cmdb_tables[].display_name` | string | yes | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `cmdb_tables[].ci_table_name` | string | yes | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `cmdb_tables[].query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `cmdb_tables[].field_mappings` | array of object | yes | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be marked as query fields. Min items: 2. Max items: 20. | | `cmdb_tables[].field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `cmdb_tables[].field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `cmdb_tables[].field_mappings[].type` | string | | Set to `query` to use this mapping as a lookup key for matching incoming events to Configuration Items. Omit it for enrichment fields (the default). At most 3 mappings may be marked `query`, and at least one mapping must be left as an enrichment field. When no mapping is marked `query`, the `name` field is used as the query field automatically. Only `query` is accepted here — any other value is rejected. One of: `query`. | Example: Create a ServiceNow enrichment integration ```json { "name": "Production CMDB Integration", "description": "Enrichment data from production ServiceNow instance", "cmdb_tables": [ { "display_name": "Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1", "field_mappings": [ { "servicenow_field": "name", "event_field": "source" }, { "servicenow_field": "operational_status", "event_field": "Operational Status" }, { "servicenow_field": "support_group", "event_field": "Support Group" }, { "servicenow_field": "sys_class_name", "event_field": "CI Class" } ] } ] } ``` Example: Match on multiple query fields ```json { "name": "Production CMDB Integration", "description": "Match CIs on both host name and CI class", "cmdb_tables": [ { "display_name": "Servers", "ci_table_name": "cmdb_ci_server", "query_filter": "operational_status=1", "field_mappings": [ { "servicenow_field": "name", "event_field": "host", "type": "query" }, { "servicenow_field": "sys_class_name", "event_field": "ci_class", "type": "query" }, { "servicenow_field": "support_group", "event_field": "Support Group" }, { "servicenow_field": "location", "event_field": "Location" } ] } ] } ``` ## Response 201 The ServiceNow enrichment integration was created successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | | | | `integration.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the integration. Read-only. | | `integration.name` | string | | The name of the integration. | | `integration.description` | string \| null | | An optional description of the integration. | | `integration.cmdb_tables` | array of object | | The ServiceNow CMDB table configurations belonging to this integration. An integration must have at least 1 and at most 8 tables. | | `integration.cmdb_tables[].id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. Read-only. | | `integration.cmdb_tables[].display_name` | string | | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `integration.cmdb_tables[].ci_table_name` | string | | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `integration.cmdb_tables[].query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `integration.cmdb_tables[].field_mappings` | array of object | | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be designated as query fields. | | `integration.cmdb_tables[].field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `integration.cmdb_tables[].field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `integration.cmdb_tables[].field_mappings[].type` | string | | Determines how the field is used during enrichment. `enriched` fields add contextual data to a matched event, while `query` fields are used to match incoming events to Configuration Items. When no mapping specifies a `type`, the field defaults to `enriched` and the `name` field is automatically used as the single query field. To match on a different field — or on more than one field — set `type: query` on those mappings; in that mode `name` is no longer used as a query field unless it is itself marked `query`. Up to 3 query fields may be configured, and when more than one is set an event must contain a matching value for every query field to be enriched (logical AND). At least one mapping must be an enriched field. In responses, a mapping's `type` is `query`, `enriched`, or `discriminator`. `discriminator` is assigned automatically to the `sys_id` field of `cmdb_rel_ci` relationship tables to distinguish relationship types; it appears in responses but cannot be set on requests. One of: `query`, `enriched`, `discriminator`. | | `integration.cmdb_tables[].status` | string | | The current data synchronization status of the table. `disabled`: sync is not enabled (the default for newly created tables). `syncing`: an initial sync is in progress. `active`: sync is healthy and incremental updates are running. `error`: sync failed (check the credentials or table configuration). Read-only. One of: `disabled`, `syncing`, `active`, `error`. | | `integration.cmdb_tables[].created_at` | string (date-time) | | The date/time the table configuration was created. Read-only. | | `integration.cmdb_tables[].updated_at` | string (date-time) | | The date/time the table configuration was last updated. Read-only. | | `integration.cmdb_tables[].deleted_at` | string \| null (date-time) | | The date/time the table configuration was deleted, or `null` if it has not been deleted. Read-only. | | `integration.credentials` | object, nullable | | The ServiceNow credentials associated with the account, or `null` if no credentials have been configured. Credentials are managed through the credentials endpoints, not through this object. Read-only. | | `integration.credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `integration.credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `integration.credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `integration.credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `integration.credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `integration.credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `integration.credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | | `integration.created_at` | string (date-time) | | The date/time the integration was created. Read-only. | | `integration.updated_at` | string (date-time) | | The date/time the integration was last updated. Read-only. | Example: Example Response ```json { "integration": { "id": "01HQXYZ9ABCDEFGHIJKLMNOPQR", "name": "Production CMDB Integration", "description": "Enrichment data from production ServiceNow instance", "cmdb_tables": [ { "id": "01HTABC8DEFGHIJKLMNOPQRSTU", "display_name": "Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1", "field_mappings": [ { "servicenow_field": "name", "event_field": "source", "type": "query" }, { "servicenow_field": "operational_status", "event_field": "Operational Status", "type": "enriched" }, { "servicenow_field": "support_group", "event_field": "Support Group", "type": "enriched" }, { "servicenow_field": "sys_class_name", "event_field": "CI Class", "type": "enriched" } ], "status": "disabled", "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T18:24:00Z", "deleted_at": null } ], "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T18:20:00Z", "deleted_at": null }, "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T18:24:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/delete-service-now-credentials # Delete ServiceNow credentials `DELETE https://api.pagerduty.com/enrichment/integrations/servicenow/credentials/{credentials_id}` Deletes the ServiceNow credentials. Credentials cannot be deleted while they are associated with an existing ServiceNow integration; delete the integration first. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `credentials_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow credentials. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The ServiceNow credentials were deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/delete-service-now-integration # Delete a ServiceNow integration `DELETE https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}` Deletes a ServiceNow enrichment integration, including all of its CMDB table configurations and their generated enrichment schemas, and disables any associated data synchronization. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The ServiceNow integration was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/delete-service-now-table # Remove a CMDB table `DELETE https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}` Removes a ServiceNow CMDB table configuration from an integration. The table's generated enrichment schema is removed and its data synchronization is disabled. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | | `table_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The CMDB table was removed successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/enable-service-now-table-sync # Enable CMDB table sync `POST https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}/enable` Enables data synchronization for a ServiceNow CMDB table configuration. Once enabled, the table's enrichment schema is populated with CI data from ServiceNow and kept up to date with periodic syncs. This operation is idempotent — enabling an already-enabled table succeeds. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | | `table_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Data synchronization was enabled for the CMDB table. This operation is idempotent — enabling an already-enabled table succeeds. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | The outcome of the enable operation. | | `message` | string | | A human-readable message describing the result. | Example: Example Response ```json { "status": "enabled", "message": "Data synchronization enabled for table" } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/get-service-now-credentials # Get ServiceNow credentials `GET https://api.pagerduty.com/enrichment/integrations/servicenow/credentials/{credentials_id}` Retrieves the ServiceNow credentials by ID. The password is never returned. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `credentials_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow credentials. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requested ServiceNow credentials. The password is never returned. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `credentials` | object | | | | `credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | Example: Example Response ```json { "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T18:20:00Z", "deleted_at": null } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/get-service-now-integration # Get a ServiceNow integration `GET https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}` Retrieves a single ServiceNow enrichment integration by ID, including its CMDB tables, field mappings, the current sync status of each table, and credentials. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requested ServiceNow enrichment integration, including its CMDB tables, field mappings, and credentials. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | | | | `integration.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the integration. Read-only. | | `integration.name` | string | | The name of the integration. | | `integration.description` | string \| null | | An optional description of the integration. | | `integration.cmdb_tables` | array of object | | The ServiceNow CMDB table configurations belonging to this integration. An integration must have at least 1 and at most 8 tables. | | `integration.cmdb_tables[].id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. Read-only. | | `integration.cmdb_tables[].display_name` | string | | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `integration.cmdb_tables[].ci_table_name` | string | | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `integration.cmdb_tables[].query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `integration.cmdb_tables[].field_mappings` | array of object | | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be designated as query fields. | | `integration.cmdb_tables[].field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `integration.cmdb_tables[].field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `integration.cmdb_tables[].field_mappings[].type` | string | | Determines how the field is used during enrichment. `enriched` fields add contextual data to a matched event, while `query` fields are used to match incoming events to Configuration Items. When no mapping specifies a `type`, the field defaults to `enriched` and the `name` field is automatically used as the single query field. To match on a different field — or on more than one field — set `type: query` on those mappings; in that mode `name` is no longer used as a query field unless it is itself marked `query`. Up to 3 query fields may be configured, and when more than one is set an event must contain a matching value for every query field to be enriched (logical AND). At least one mapping must be an enriched field. In responses, a mapping's `type` is `query`, `enriched`, or `discriminator`. `discriminator` is assigned automatically to the `sys_id` field of `cmdb_rel_ci` relationship tables to distinguish relationship types; it appears in responses but cannot be set on requests. One of: `query`, `enriched`, `discriminator`. | | `integration.cmdb_tables[].status` | string | | The current data synchronization status of the table. `disabled`: sync is not enabled (the default for newly created tables). `syncing`: an initial sync is in progress. `active`: sync is healthy and incremental updates are running. `error`: sync failed (check the credentials or table configuration). Read-only. One of: `disabled`, `syncing`, `active`, `error`. | | `integration.cmdb_tables[].created_at` | string (date-time) | | The date/time the table configuration was created. Read-only. | | `integration.cmdb_tables[].updated_at` | string (date-time) | | The date/time the table configuration was last updated. Read-only. | | `integration.cmdb_tables[].deleted_at` | string \| null (date-time) | | The date/time the table configuration was deleted, or `null` if it has not been deleted. Read-only. | | `integration.credentials` | object, nullable | | The ServiceNow credentials associated with the account, or `null` if no credentials have been configured. Credentials are managed through the credentials endpoints, not through this object. Read-only. | | `integration.credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `integration.credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `integration.credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `integration.credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `integration.credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `integration.credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `integration.credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | | `integration.created_at` | string (date-time) | | The date/time the integration was created. Read-only. | | `integration.updated_at` | string (date-time) | | The date/time the integration was last updated. Read-only. | Example: Example Response ```json { "integration": { "id": "01HQXYZ9ABCDEFGHIJKLMNOPQR", "name": "Production CMDB Integration", "description": "Enrichment data from production ServiceNow instance", "cmdb_tables": [ { "id": "01HTABC8DEFGHIJKLMNOPQRSTU", "display_name": "Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1", "field_mappings": [ { "servicenow_field": "name", "event_field": "source", "type": "query" }, { "servicenow_field": "operational_status", "event_field": "Operational Status", "type": "enriched" }, { "servicenow_field": "support_group", "event_field": "Support Group", "type": "enriched" }, { "servicenow_field": "sys_class_name", "event_field": "CI Class", "type": "enriched" } ], "status": "active", "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T19:05:00Z", "deleted_at": null } ], "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T18:20:00Z", "deleted_at": null }, "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T19:05:00Z" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/list-service-now-integrations # List ServiceNow integrations `GET https://api.pagerduty.com/enrichment/integrations/servicenow` Lists the ServiceNow enrichment integrations for the account, including their CMDB tables, field mappings, and credentials. Because only one integration is allowed per account, this returns at most one integration. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The list of ServiceNow enrichment integrations for the account. Returns at most one integration due to product limits. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integrations` | array of object | | The list of ServiceNow enrichment integrations. | | `integrations[].id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the integration. Read-only. | | `integrations[].name` | string | | The name of the integration. | | `integrations[].description` | string \| null | | An optional description of the integration. | | `integrations[].cmdb_tables` | array of object | | The ServiceNow CMDB table configurations belonging to this integration. An integration must have at least 1 and at most 8 tables. | | `integrations[].cmdb_tables[].id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. Read-only. | | `integrations[].cmdb_tables[].display_name` | string | | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `integrations[].cmdb_tables[].ci_table_name` | string | | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `integrations[].cmdb_tables[].query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `integrations[].cmdb_tables[].field_mappings` | array of object | | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be designated as query fields. | | `integrations[].cmdb_tables[].field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `integrations[].cmdb_tables[].field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `integrations[].cmdb_tables[].field_mappings[].type` | string | | Determines how the field is used during enrichment. `enriched` fields add contextual data to a matched event, while `query` fields are used to match incoming events to Configuration Items. When no mapping specifies a `type`, the field defaults to `enriched` and the `name` field is automatically used as the single query field. To match on a different field — or on more than one field — set `type: query` on those mappings; in that mode `name` is no longer used as a query field unless it is itself marked `query`. Up to 3 query fields may be configured, and when more than one is set an event must contain a matching value for every query field to be enriched (logical AND). At least one mapping must be an enriched field. In responses, a mapping's `type` is `query`, `enriched`, or `discriminator`. `discriminator` is assigned automatically to the `sys_id` field of `cmdb_rel_ci` relationship tables to distinguish relationship types; it appears in responses but cannot be set on requests. One of: `query`, `enriched`, `discriminator`. | | `integrations[].cmdb_tables[].status` | string | | The current data synchronization status of the table. `disabled`: sync is not enabled (the default for newly created tables). `syncing`: an initial sync is in progress. `active`: sync is healthy and incremental updates are running. `error`: sync failed (check the credentials or table configuration). Read-only. One of: `disabled`, `syncing`, `active`, `error`. | | `integrations[].cmdb_tables[].created_at` | string (date-time) | | The date/time the table configuration was created. Read-only. | | `integrations[].cmdb_tables[].updated_at` | string (date-time) | | The date/time the table configuration was last updated. Read-only. | | `integrations[].cmdb_tables[].deleted_at` | string \| null (date-time) | | The date/time the table configuration was deleted, or `null` if it has not been deleted. Read-only. | | `integrations[].credentials` | object, nullable | | The ServiceNow credentials associated with the account, or `null` if no credentials have been configured. Credentials are managed through the credentials endpoints, not through this object. Read-only. | | `integrations[].credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `integrations[].credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `integrations[].credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `integrations[].credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `integrations[].credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `integrations[].credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `integrations[].credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | | `integrations[].created_at` | string (date-time) | | The date/time the integration was created. Read-only. | | `integrations[].updated_at` | string (date-time) | | The date/time the integration was last updated. Read-only. | Example: Example Response ```json { "integrations": [ { "id": "01HQXYZ9ABCDEFGHIJKLMNOPQR", "name": "Production CMDB Integration", "description": "Enrichment data from production ServiceNow instance", "cmdb_tables": [ { "id": "01HTABC8DEFGHIJKLMNOPQRSTU", "display_name": "Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1", "field_mappings": [ { "servicenow_field": "name", "event_field": "source", "type": "query" }, { "servicenow_field": "support_group", "event_field": "Support Group", "type": "enriched" } ], "status": "active", "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T19:05:00Z", "deleted_at": null } ], "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T18:20:00Z", "deleted_at": null }, "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T19:05:00Z" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/test-service-now-table # Test a CMDB table `GET https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}/test` Validates a ServiceNow CMDB table configuration by running a live query against ServiceNow and returning up to 10 sample records. Use this before enabling synchronization to confirm that the credentials, table name, query filter, and mapped fields are correct. Records are returned keyed by ServiceNow field name. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | | `table_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Up to 10 sample records returned from a live query against ServiceNow. The records are keyed by ServiceNow field name (not the mapped `event_field` names), so you can verify that the correct ServiceNow fields are configured. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `enrichment_data` | array of object | | Sample records retrieved from ServiceNow, each keyed by ServiceNow field name. | Example: Example Response ```json { "enrichment_data": [ { "name": "core-switch-01", "operational_status": "1", "support_group": "Network Operations", "sys_class_name": "cmdb_ci_ip_switch" }, { "name": "core-switch-02", "operational_status": "1", "support_group": "Network Operations", "sys_class_name": "cmdb_ci_ip_switch" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/update-service-now-credentials # Update ServiceNow credentials `PUT https://api.pagerduty.com/enrichment/integrations/servicenow/credentials/{credentials_id}` Updates the ServiceNow credentials. Supports partial updates — only the fields provided in the request are changed. If a password is provided, it replaces the stored password. The password is never returned. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `credentials_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow credentials. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The credential fields to update. Supports partial updates — only the fields provided are changed. | Field | Type | Required | Description | |---|---|---|---| | `credentials` | object | yes | | | `credentials.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the credentials. Read-only. | | `credentials.instance_endpoint` | string | | The ServiceNow instance URL (for example, `https://your-instance.service-now.com`). | | `credentials.user` | string | | The ServiceNow username used to authenticate API requests. The user must have read access to the configured CMDB tables. | | `credentials.password` | string | | The ServiceNow password. Only accepted in requests and never returned in responses. Write-only. | | `credentials.created_at` | string (date-time) | | The date/time the credentials were created. Read-only. | | `credentials.updated_at` | string (date-time) | | The date/time the credentials were last updated. Read-only. | | `credentials.deleted_at` | string \| null (date-time) | | The date/time the credentials were deleted, or `null` if they have not been deleted. Read-only. | Example: Update ServiceNow credentials ```json { "credentials": { "instance_endpoint": "https://your-instance.service-now.com", "password": "YOUR_NEW_SERVICENOW_PASSWORD" } } ``` ## Response 200 The ServiceNow credentials were updated successfully. The password is never returned. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `credentials` | object | | Same fields as `credentials` above. | Example: Example Response ```json { "credentials": { "id": "01HV2C3D4E5F6G7H8J9K0LMNPQ", "instance_endpoint": "https://your-instance.service-now.com", "user": "integration_user", "created_at": "2026-06-30T18:20:00Z", "updated_at": "2026-06-30T21:00:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-integrations/update-service-now-table # Update a CMDB table `PUT https://api.pagerduty.com/enrichment/integrations/servicenow/{integration_id}/tables/{table_id}` Replaces a ServiceNow CMDB table configuration. This is a full replacement — all fields, including `ci_table_name` and the complete `field_mappings` list, must be provided. A table can only be updated while its synchronization is disabled and before its initial backfill has started. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the ServiceNow enrichment integration. | | `table_id` | string | yes | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The replacement CMDB table configuration. This is a full replacement — all fields, including `ci_table_name` and the complete `field_mappings` list, must be provided. A table can only be updated while its sync is disabled and before its initial backfill has started. | Field | Type | Required | Description | |---|---|---|---| | `cmdb_table` | object | yes | | | `cmdb_table.display_name` | string | yes | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `cmdb_table.ci_table_name` | string | yes | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `cmdb_table.query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `cmdb_table.field_mappings` | array of object | yes | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be marked as query fields. Min items: 2. Max items: 20. | | `cmdb_table.field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `cmdb_table.field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `cmdb_table.field_mappings[].type` | string | | Set to `query` to use this mapping as a lookup key for matching incoming events to Configuration Items. Omit it for enrichment fields (the default). At most 3 mappings may be marked `query`, and at least one mapping must be left as an enrichment field. When no mapping is marked `query`, the `name` field is used as the query field automatically. Only `query` is accepted here — any other value is rejected. One of: `query`. | Example: Update a CMDB table configuration ```json { "cmdb_table": { "display_name": "Production Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1^u_environment=production", "field_mappings": [ { "servicenow_field": "name", "event_field": "source" }, { "servicenow_field": "operational_status", "event_field": "Operational Status" }, { "servicenow_field": "sys_class_name", "event_field": "CI Class" }, { "servicenow_field": "support_group.name", "event_field": "Support Team" } ] } } ``` ## Response 200 The CMDB table configuration was updated successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cmdb_table` | object | | | | `cmdb_table.id` | string | | Base32-encoded UUID v7 (26 uppercase alphanumeric characters) identifying the CMDB table configuration. Read-only. | | `cmdb_table.display_name` | string | | A human-readable name for the CMDB table configuration. This name is used to identify the generated enrichment schema in the Event Enrichment rule editor. | | `cmdb_table.ci_table_name` | string | | The name of the ServiceNow CMDB table to synchronize (for example, `cmdb_ci_server` or `cmdb_ci_ip_switch`). Table names are case-sensitive. | | `cmdb_table.query_filter` | string \| null | | An optional ServiceNow encoded query used to limit which records are synchronized from the table (for example, `operational_status=1^u_environment=production`). Set to `null` to synchronize all records. | | `cmdb_table.field_mappings` | array of object | | The mappings between ServiceNow fields and event fields. Must contain between 2 and 20 mappings, including at least one enrichment field. At most 3 mappings may be designated as query fields. | | `cmdb_table.field_mappings[].servicenow_field` | string | yes | The ServiceNow field (column) to read the value from. Dot-walked fields are supported to traverse relationships (for example, `support_group.manager.email`). | | `cmdb_table.field_mappings[].event_field` | string | yes | The event field that the ServiceNow value is mapped to. | | `cmdb_table.field_mappings[].type` | string | | Determines how the field is used during enrichment. `enriched` fields add contextual data to a matched event, while `query` fields are used to match incoming events to Configuration Items. When no mapping specifies a `type`, the field defaults to `enriched` and the `name` field is automatically used as the single query field. To match on a different field — or on more than one field — set `type: query` on those mappings; in that mode `name` is no longer used as a query field unless it is itself marked `query`. Up to 3 query fields may be configured, and when more than one is set an event must contain a matching value for every query field to be enriched (logical AND). At least one mapping must be an enriched field. In responses, a mapping's `type` is `query`, `enriched`, or `discriminator`. `discriminator` is assigned automatically to the `sys_id` field of `cmdb_rel_ci` relationship tables to distinguish relationship types; it appears in responses but cannot be set on requests. One of: `query`, `enriched`, `discriminator`. | | `cmdb_table.status` | string | | The current data synchronization status of the table. `disabled`: sync is not enabled (the default for newly created tables). `syncing`: an initial sync is in progress. `active`: sync is healthy and incremental updates are running. `error`: sync failed (check the credentials or table configuration). Read-only. One of: `disabled`, `syncing`, `active`, `error`. | | `cmdb_table.created_at` | string (date-time) | | The date/time the table configuration was created. Read-only. | | `cmdb_table.updated_at` | string (date-time) | | The date/time the table configuration was last updated. Read-only. | | `cmdb_table.deleted_at` | string \| null (date-time) | | The date/time the table configuration was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "cmdb_table": { "id": "01HTABC8DEFGHIJKLMNOPQRSTU", "display_name": "Production Network Switches", "ci_table_name": "cmdb_ci_ip_switch", "query_filter": "operational_status=1^u_environment=production", "field_mappings": [ { "servicenow_field": "name", "event_field": "source", "type": "query" }, { "servicenow_field": "operational_status", "event_field": "Operational Status", "type": "enriched" }, { "servicenow_field": "sys_class_name", "event_field": "CI Class", "type": "enriched" }, { "servicenow_field": "support_group.name", "event_field": "Support Team", "type": "enriched" } ], "status": "disabled", "created_at": "2026-06-30T18:24:00Z", "updated_at": "2026-06-30T20:30:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/create-enrichment-schema # Create an enrichment schema `POST https://api.pagerduty.com/enrichment/schemas` Creates an enrichment schema. Provide a JSON body to define the schema explicitly (returns `201`), or upload a CSV file as `multipart/form-data` or `text/csv` to auto-generate a schema from the file's columns — the first column becomes a query field and the rest become enriched fields (returns `202` once the file is accepted for processing). A schema must include 1-3 query fields and at least one enriched field, up to 25 fields total, with unique (case-insensitive) field names. Schemas created through the API are always `CSV`, and an account may have at most 25 CSV schemas. CSV uploads are limited to 10 MB. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `filename` | string | | The filename for the CSV content. Required when creating a schema from a `text/csv` body; optional for `text/csv` record uploads. Ignored for `multipart/form-data` and JSON requests. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB. | Field | Type | Required | Description | |---|---|---|---| | `integration_type` | string | | The schema source. Only `CSV` is supported through the API; the schema is always recorded as `CSV` regardless of the value sent. One of: `CSV`. | | `name` | string | yes | Display name of the enrichment schema. Max length: 50. | | `description` | string | | Description of this set of enrichment data. Max length: 2048. | | `fields` | array of object | yes | The schema fields. Must include 1-3 query fields and at least one enriched field, up to 25 fields total. Field names must be unique (case-insensitive). Min items: 2. Max items: 25. | | `fields[].name` | string | yes | The name of the field. Must be unique within the schema (case-insensitive). Max length: 256. | | `fields[].type` | string | yes | How the field is used. `query` fields match incoming events to records (case-insensitive); `enriched` fields carry the data added to a matched event. One of: `query`, `enriched`. | Example: Create a schema with multiple query fields ```json { "integration_type": "CSV", "name": "Application Environment Enrichment", "description": "Maps applications to team and runbook info by environment", "fields": [ { "name": "Application", "type": "query" }, { "name": "Environment", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Team", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ] } ``` ## Request body (`multipart/form-data`) — required The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB. | Field | Type | Required | Description | |---|---|---|---| | `file` | string | yes | The CSV file to upload (max 10 MB). The schema name is derived from the filename. | ## Request body (`text/csv`) — required The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB. Type: string ## Response 201 The enrichment schema was created successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | | | | `schema.id` | string (uuid) | | Unique identifier for the enrichment schema. Read-only. | | `schema.type` | string | | The type of the resource. Read-only. | | `schema.integration_type` | string | | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. | | `schema.name` | string | | Display name of the enrichment schema. Max length: 50. | | `schema.description` | string \| null | | Description of this set of enrichment data. Max length: 2048. | | `schema.fields` | array of object | | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. | | `schema.fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. | | `schema.fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. | | `schema.created_at` | string (date-time) | | Timestamp when the schema was created. Read-only. | | `schema.updated_at` | string (date-time) | | Timestamp when the schema was last updated. Read-only. | | `schema.deleted_at` | string \| null (date-time) | | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "schema": { "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "type": "enrichment_schema", "integration_type": "CSV", "name": "Team Lead and Runbooks", "description": "Attaches SME and Runbook URLs to Incident", "fields": [ { "name": "Application", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ], "created_at": "2026-06-30T15:17:30Z", "updated_at": "2026-06-30T15:17:30Z", "deleted_at": null } } ``` ## Response 202 The schema was created from the uploaded CSV and the file was accepted for asynchronous processing. The records become queryable once processing completes. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | | Same fields as `schema` above. | Example: Example Response ```json { "schema": { "id": "b620bbb5-2571-4b7a-b0c6-47c55bd491d0", "type": "enrichment_schema", "integration_type": "CSV", "name": "users", "description": "Auto generated schema from CSV upload", "fields": [ { "name": "email", "type": "query" }, { "name": "team", "type": "enriched" }, { "name": "manager", "type": "enriched" } ], "created_at": "2026-06-30T15:20:00Z", "updated_at": "2026-06-30T15:20:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/delete-enrichment-record # Delete an enrichment record `DELETE https://api.pagerduty.com/enrichment/schemas/{schema_id}/records/{record_id}` Deletes a single enrichment record by ID and returns the deleted record. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | | `record_id` | string | yes | The ID of the enrichment record. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The enrichment record was deleted successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `record` | object | | | | `record.record_id` | string | | Unique identifier for this enrichment record. Read-only. | | `record.type` | string | | The type of the resource. Read-only. | | `record.created_at` | string (date-time) | | Timestamp when the record was created. Read-only. | | `record.enrichment_data` | object | | The enrichment data for this record, as key-value pairs keyed by field name. | Example: Example Response ```json { "record": { "record_id": "a3b2c1d4e5f6", "type": "enrichment_record", "created_at": "2026-06-30T15:17:30Z", "enrichment_data": { "Application": "Auth Service", "Manager": "alice@example.com", "Runbook URL": "https://runbooks.example.com/auth" } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/delete-enrichment-schema # Delete an enrichment schema `DELETE https://api.pagerduty.com/enrichment/schemas/{schema_id}` Soft-deletes an enrichment schema and returns the deleted schema. Only `CSV` schemas can be deleted; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The enrichment schema was deleted successfully. Only `CSV` schemas can be deleted. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | | | | `schema.id` | string (uuid) | | Unique identifier for the enrichment schema. Read-only. | | `schema.type` | string | | The type of the resource. Read-only. | | `schema.integration_type` | string | | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. | | `schema.name` | string | | Display name of the enrichment schema. Max length: 50. | | `schema.description` | string \| null | | Description of this set of enrichment data. Max length: 2048. | | `schema.fields` | array of object | | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. | | `schema.fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. | | `schema.fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. | | `schema.created_at` | string (date-time) | | Timestamp when the schema was created. Read-only. | | `schema.updated_at` | string (date-time) | | Timestamp when the schema was last updated. Read-only. | | `schema.deleted_at` | string \| null (date-time) | | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "schema": { "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "type": "enrichment_schema", "integration_type": "CSV", "name": "Team Lead and Runbooks", "description": "Attaches SME and Runbook URLs to Incident", "fields": [ { "name": "Application", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ], "created_at": "2026-06-30T15:17:30Z", "updated_at": "2026-06-30T15:17:30Z", "deleted_at": "2026-06-30T16:45:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/get-enrichment-schema # Get an enrichment schema `GET https://api.pagerduty.com/enrichment/schemas/{schema_id}` Retrieves a specific enrichment schema by ID. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requested enrichment schema. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | | | | `schema.id` | string (uuid) | | Unique identifier for the enrichment schema. Read-only. | | `schema.type` | string | | The type of the resource. Read-only. | | `schema.integration_type` | string | | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. | | `schema.name` | string | | Display name of the enrichment schema. Max length: 50. | | `schema.description` | string \| null | | Description of this set of enrichment data. Max length: 2048. | | `schema.fields` | array of object | | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. | | `schema.fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. | | `schema.fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. | | `schema.created_at` | string (date-time) | | Timestamp when the schema was created. Read-only. | | `schema.updated_at` | string (date-time) | | Timestamp when the schema was last updated. Read-only. | | `schema.deleted_at` | string \| null (date-time) | | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "schema": { "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "type": "enrichment_schema", "integration_type": "CSV", "name": "Team Lead and Runbooks", "description": "Attaches SME and Runbook URLs to Incident", "fields": [ { "name": "Application", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ], "created_at": "2026-06-30T15:17:30Z", "updated_at": "2026-06-30T15:17:30Z", "deleted_at": null } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/list-enrichment-records # List enrichment records `GET https://api.pagerduty.com/enrichment/schemas/{schema_id}/records` Retrieves a page of enrichment records for a schema. Results are cursor-paginated. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The maximum number of records to return per page (1-100). Default: `100`. Minimum: 1. Maximum: 100. | | `cursor` | string | | Pagination cursor returned by a previous list request. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A page of enrichment records for the schema. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | | The schema the records belong to. | | `records` | array of object | | The page of enrichment records. | | `records[].record_id` | string | | Unique identifier for this enrichment record. Read-only. | | `records[].type` | string | | The type of the resource. Read-only. | | `records[].created_at` | string (date-time) | | Timestamp when the record was created. Read-only. | | `records[].enrichment_data` | object | | The enrichment data for this record, as key-value pairs keyed by field name. | | `next_cursor` | string \| null | | Cursor for fetching the next page, or `null` if there are no more pages. | Example: Example Response ```json { "schema_id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "records": [ { "record_id": "a3b2c1d4e5f6", "type": "enrichment_record", "created_at": "2026-06-30T15:17:30Z", "enrichment_data": { "Application": "Auth Service", "Manager": "alice@example.com", "Runbook URL": "https://runbooks.example.com/auth" } } ], "next_cursor": "eyJuZXh0IjoiYTNiMmMxZDRlNWY2In0=" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/list-enrichment-schemas # List enrichment schemas `GET https://api.pagerduty.com/enrichment/schemas` Lists all enrichment schemas for the account. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The list of enrichment schemas for the account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schemas` | array of object | | The list of enrichment schemas. | | `schemas[].id` | string (uuid) | | Unique identifier for the enrichment schema. Read-only. | | `schemas[].type` | string | | The type of the resource. Read-only. | | `schemas[].integration_type` | string | | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. | | `schemas[].name` | string | | Display name of the enrichment schema. Max length: 50. | | `schemas[].description` | string \| null | | Description of this set of enrichment data. Max length: 2048. | | `schemas[].fields` | array of object | | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. | | `schemas[].fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. | | `schemas[].fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. | | `schemas[].created_at` | string (date-time) | | Timestamp when the schema was created. Read-only. | | `schemas[].updated_at` | string (date-time) | | Timestamp when the schema was last updated. Read-only. | | `schemas[].deleted_at` | string \| null (date-time) | | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "schemas": [ { "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "type": "enrichment_schema", "integration_type": "CSV", "name": "Team Lead and Runbooks", "description": "Attaches SME and Runbook URLs to Incident", "fields": [ { "name": "Application", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ], "created_at": "2026-06-30T15:17:30Z", "updated_at": "2026-06-30T15:17:30Z", "deleted_at": null } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/query-enrichment-data # Query enrichment data `POST https://api.pagerduty.com/enrichment/query` Query an enrichment schema for records matching a set of field values. Supply up to 3 query fields; all must match. Returns at most one record for standard schemas, or multiple records for schemas that use a discriminator field. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The schema and query field values to match enrichment records against. | Field | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema to query. | | `query` | array of object | yes | The query field values to match against. Up to 3 query fields may be supplied; all must match. Min items: 1. Max items: 3. | | `query[].field` | string | yes | The query field name. | | `query[].value` | string | yes | The value to match for this field. | Example: Query enrichment data ```json { "schema_id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "query": [ { "field": "Application", "value": "Authorization" }, { "field": "Environment", "value": "production" } ] } ``` ## Response 200 The enrichment records matching the query. Returns 0-1 records for standard schemas, or 0-N records for schemas that use a discriminator field. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | | The enrichment records matching the query. | | `records[].record_id` | string | | Unique identifier for this enrichment record. Read-only. | | `records[].type` | string | | The type of the resource. Read-only. | | `records[].created_at` | string (date-time) | | Timestamp when the record was created. Read-only. | | `records[].enrichment_data` | object | | The enrichment data for this record, as key-value pairs keyed by field name. | Example: Example Response ```json { "records": [ { "record_id": "a3b2c1d4e5f6", "type": "enrichment_record", "created_at": "2026-06-30T15:17:30Z", "enrichment_data": { "Application": "Authorization", "Environment": "production", "Manager": "alice@example.com" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/update-enrichment-schema # Update an enrichment schema `PUT https://api.pagerduty.com/enrichment/schemas/{schema_id}` Updates the name and/or description of an enrichment schema. At least one of `name` or `description` must be provided. Schema fields cannot be changed after creation. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The schema fields to update. At least one of `name` or `description` must be provided. | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | yes | | | `schema.name` | string | | Display name of the enrichment schema. Max length: 50. | | `schema.description` | string | | Description of this set of enrichment data. Max length: 2048. | Example: Rename a schema ```json { "schema": { "name": "Team Leads and Runbooks", "description": "Attaches SME and Runbook URLs to incidents" } } ``` ## Response 200 The enrichment schema was updated successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schema` | object | | | | `schema.id` | string (uuid) | | Unique identifier for the enrichment schema. Read-only. | | `schema.type` | string | | The type of the resource. Read-only. | | `schema.integration_type` | string | | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. | | `schema.name` | string | | Display name of the enrichment schema. Max length: 50. | | `schema.description` | string \| null | | Description of this set of enrichment data. Max length: 2048. | | `schema.fields` | array of object | | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. | | `schema.fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. | | `schema.fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. | | `schema.created_at` | string (date-time) | | Timestamp when the schema was created. Read-only. | | `schema.updated_at` | string (date-time) | | Timestamp when the schema was last updated. Read-only. | | `schema.deleted_at` | string \| null (date-time) | | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. | Example: Example Response ```json { "schema": { "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "type": "enrichment_schema", "integration_type": "CSV", "name": "Team Leads and Runbooks", "description": "Attaches SME and Runbook URLs to incidents", "fields": [ { "name": "Application", "type": "query" }, { "name": "Manager", "type": "enriched" }, { "name": "Runbook URL", "type": "enriched" } ], "created_at": "2026-06-30T15:17:30Z", "updated_at": "2026-06-30T16:02:00Z", "deleted_at": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/enrichment-schemas/upload-enrichment-csv # Upload CSV records `POST https://api.pagerduty.com/enrichment/schemas/{schema_id}/records` Uploads a CSV file of enrichment records into an existing schema, as `multipart/form-data` or `text/csv`. The file is accepted for asynchronous processing (returns `202`) and is limited to 10 MB. The CSV columns must align with the schema's fields: missing columns result in empty values and extra columns are ignored. Records are keyed by their query-field values, so uploading a row whose query values match an existing record updates that record. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Scoped OAuth requires: `contextual_data.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `schema_id` | string (uuid) | yes | The ID of the enrichment schema. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `filename` | string | | The filename for the CSV content. Required when creating a schema from a `text/csv` body; optional for `text/csv` record uploads. Ignored for `multipart/form-data` and JSON requests. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`multipart/form-data`) — required The CSV file to upload into the schema, as `multipart/form-data` or `text/csv`. The file is streamed for asynchronous processing and is limited to 10 MB. The CSV columns must align with the schema's fields: missing columns result in empty values and extra columns are ignored. Records are keyed by their query-field values, so uploading a row whose query values match an existing record updates that record. | Field | Type | Required | Description | |---|---|---|---| | `file` | string | yes | The CSV file to upload (max 10 MB). | ## Request body (`text/csv`) — required The CSV file to upload into the schema, as `multipart/form-data` or `text/csv`. The file is streamed for asynchronous processing and is limited to 10 MB. The CSV columns must align with the schema's fields: missing columns result in empty values and extra columns are ignored. Records are keyed by their query-field values, so uploading a row whose query values match an existing record updates that record. Type: string ## Response 202 The CSV file was accepted for asynchronous processing. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `upload_id` | string (uuid) | | Unique identifier for the CSV upload operation. | | `schema_id` | string (uuid) | | The schema the CSV data is being uploaded to. | | `filename` | string \| null | | Original filename of the uploaded CSV file. | | `size_bytes` | integer (int64) | | Size of the uploaded file in bytes. | | `status` | string | | Status of the upload operation. | | `accepted_at` | string (date-time) | | Timestamp when the upload was accepted. | Example: Example Response ```json { "upload_id": "605d87a2-c67c-441e-a4cb-dbbbd94a340c", "schema_id": "b620bbb5-2571-4b7a-b0c6-47c55bd491d0", "filename": "users.csv", "size_bytes": 1024, "status": "accepted", "accepted_at": "2026-06-30T10:30:00Z" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/create-escalation-policy # Create an escalation policy `POST https://api.pagerduty.com/escalation_policies` Creates a new escalation policy. At least one escalation rule must be provided. Escalation policies define which user should be alerted at which time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#escalation-policies) Scoped OAuth requires: `escalation_policies.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | | The email address of a valid user associated with the account making the request. This is optional, and is only used for change tracking. | ## Request body (`application/json`) The escalation policy to be created. | Field | Type | Required | Description | |---|---|---|---| | `escalation_policy` | object | yes | | | `escalation_policy.id` | string | | Read-only. | | `escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.type` | string | yes | The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.name` | string | yes | The name of the escalation policy. | | `escalation_policy.description` | string | | Escalation policy description. | | `escalation_policy.num_loops` | integer | | The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `escalation_policy.on_call_handoff_notifications` | string | | Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `escalation_policy.escalation_rules` | array of object | yes | | | `escalation_policy.escalation_rules[].id` | string | | Read-only. | | `escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `escalation_policy.services` | array of object | | Read-only. Min length: 0. | | `escalation_policy.services[].id` | string | yes | Read-only. | | `escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.teams` | array of object | | Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `escalation_policy.teams[].id` | string | yes | Read-only. | | `escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "escalation_policy": { "type": "escalation_policy", "name": "Engineering Escalation Policy", "escalation_rules": [ { "escalation_delay_in_minutes": 30, "targets": [ { "id": "PEYSGVF", "type": "user_reference" } ], "escalation_rule_assignment_strategy": { "type": "round_robin" } } ], "services": [ { "id": "PIJ90N7", "type": "service_reference" } ], "num_loops": 2, "on_call_handoff_notifications": "if_has_services", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "description": "Here is the ep for the engineering team." } } ``` ## Response 201 The escalation policy that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `escalation_policy` | object | yes | Same fields as `escalation_policy` above. | Example: Response Example ```json { "escalation_policy": { "id": "PT20YPA", "type": "escalation_policy", "summary": "Engineering 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": "Engineering Escalation Policy", "escalation_rules": [ { "id": "PT20YPA", "escalation_delay_in_minutes": 22, "targets": [ { "id": "PXPGF42", "summary": "Earline Greenholt", "type": "user_reference", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" }, { "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" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/delete-escalation-policy # Delete an escalation policy `DELETE https://api.pagerduty.com/escalation_policies/{id}` Deletes an existing escalation policy and rules. The escalation policy must not be in use by any services. Escalation policies define which user should be alerted at which time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#escalation-policies) Scoped OAuth requires: `escalation_policies.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The escalation policy was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/get-escalation-policy # Get an escalation policy `GET https://api.pagerduty.com/escalation_policies/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#escalation-policies) Scoped OAuth requires: `escalation_policies.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. One of: `services`, `teams`, `targets`, `escalation_rule_assignment_strategies`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The escalation policy object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `escalation_policy` | object | yes | | | `escalation_policy.id` | string | | Read-only. | | `escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.type` | string | yes | The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.name` | string | yes | The name of the escalation policy. | | `escalation_policy.description` | string | | Escalation policy description. | | `escalation_policy.num_loops` | integer | | The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `escalation_policy.on_call_handoff_notifications` | string | | Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `escalation_policy.escalation_rules` | array of object | yes | | | `escalation_policy.escalation_rules[].id` | string | | Read-only. | | `escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `escalation_policy.services` | array of object | | Read-only. Min length: 0. | | `escalation_policy.services[].id` | string | yes | Read-only. | | `escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.teams` | array of object | | Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `escalation_policy.teams[].id` | string | yes | Read-only. | | `escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "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" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/list-escalation-policies # List escalation policies `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#escalation-policies) Scoped OAuth requires: `escalation_policies.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `user_ids[]` | array of string | | Filters the results, showing only escalation policies on which any of the users is a target. Items must be unique. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `include[]` | string | | Array of additional Models to include in response. One of: `services`, `teams`, `targets`, `escalation_rule_assignment_strategies`. Items must be unique. | | `sort_by` | string | | Used to specify the field you wish to sort the results on. One of: `name`, `name:asc`, `name:desc`. Default: `name`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of escalation policy objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `escalation_policies` | array of object | yes | | | `escalation_policies[].id` | string | | Read-only. | | `escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policies[].type` | string | yes | The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policies[].name` | string | yes | The name of the escalation policy. | | `escalation_policies[].description` | string | | Escalation policy description. | | `escalation_policies[].num_loops` | integer | | The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `escalation_policies[].on_call_handoff_notifications` | string | | Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `escalation_policies[].escalation_rules` | array of object | yes | | | `escalation_policies[].escalation_rules[].id` | string | | Read-only. | | `escalation_policies[].escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `escalation_policies[].escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `escalation_policies[].escalation_rules[].targets[].id` | string | yes | Read-only. | | `escalation_policies[].escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policies[].escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `escalation_policies[].escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policies[].escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policies[].escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `escalation_policies[].services` | array of object | | Read-only. Min length: 0. | | `escalation_policies[].services[].id` | string | yes | Read-only. | | `escalation_policies[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policies[].services[].type` | string | yes | One of: `service_reference`. | | `escalation_policies[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policies[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policies[].teams` | array of object | | Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `escalation_policies[].teams[].id` | string | yes | Read-only. | | `escalation_policies[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policies[].teams[].type` | string | yes | One of: `team_reference`. | | `escalation_policies[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policies[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/list-escalation-policy-audit-records # List audit records for an escalation policy `GET https://api.pagerduty.com/escalation_policies/{id}/audit/records` The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PD_ASSIGN_TEAM_TO_ESCALATION_POLICY", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_TEAM123", "summary": "Devops", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" } ], "name": "teams" } ], "resource": { "id": "PD_ESCALATION_ID", "summary": "DevOps Escalation", "type": "escalation_policy_reference", "self": "https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID", "html_url": "https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID" } }, "execution_context": { "request_id": "0cc413fb-8e7d-4414-b4bc-b7578bf3ba77" }, "execution_time": "2021-01-05T16:33:52.026Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_ESCALATION_ID", "summary": "DevOps Escalation", "type": "escalation_policy_reference", "self": "https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID", "html_url": "https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID" } }, { "id": "PD_CREATE_ESCALATION_POLICY", "action": "create", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "name", "value": "DevOps Escalation" }, { "name": "description", "value": "Escalation Policy for devops" }, { "name": "num_loops", "value": "1" } ], "resource": { "id": "PD_ESCALATION_ID", "summary": "DevOps Escalation", "type": "escalation_policy_reference", "self": "https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID", "html_url": "https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID" } }, "execution_context": { "request_id": "0cc413fb-8e7d-4414-b4bc-b7578bf3ba77" }, "execution_time": "2021-01-05T16:33:51.951Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_ESCALATION_ID", "summary": "DevOps Escalation", "type": "escalation_policy_reference", "self": "https://api.pagerduty.com/escalation_policies/PD_ESCALATION_ID", "html_url": "https://mydomain.pagerduty.com/escalation_policies/PD_ESCALATION_ID" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/escalation-policies/update-escalation-policy # Update an escalation policy `PUT https://api.pagerduty.com/escalation_policies/{id}` Updates an existing escalation policy and rules. Escalation policies define which user should be alerted at which time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#escalation-policies) Scoped OAuth requires: `escalation_policies.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The escalation policy to be updated. | Field | Type | Required | Description | |---|---|---|---| | `escalation_policy` | object | yes | | | `escalation_policy.id` | string | | Read-only. | | `escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.type` | string | yes | The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.name` | string | yes | The name of the escalation policy. | | `escalation_policy.description` | string | | Escalation policy description. | | `escalation_policy.num_loops` | integer | | The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `escalation_policy.on_call_handoff_notifications` | string | | Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `escalation_policy.escalation_rules` | array of object | yes | | | `escalation_policy.escalation_rules[].id` | string | | Read-only. | | `escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `escalation_policy.services` | array of object | | Read-only. Min length: 0. | | `escalation_policy.services[].id` | string | yes | Read-only. | | `escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policy.teams` | array of object | | Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `escalation_policy.teams[].id` | string | yes | Read-only. | | `escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "escalation_policy": { "type": "escalation_policy", "name": "Engineering Escalation Policy", "escalation_rules": [ { "escalation_delay_in_minutes": 30, "targets": [ { "id": "PEYSGVF", "type": "user_reference" } ], "escalation_rule_assignment_strategy": { "type": "round_robin" } } ], "services": [ { "id": "PIJ90N7", "type": "service_reference" } ], "num_loops": 2, "on_call_handoff_notifications": "if_has_services", "teams": [ { "id": "PQ9K7I8", "type": "team_reference" } ], "description": "Here is the ep for the engineering team." } } ``` ## Response 200 The escalation policy that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `escalation_policy` | object | yes | Same fields as `escalation_policy` above. | Example: Response Example ```json { "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" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/add-event-enrichment-associations # Add Event Enrichment associations `POST https://api.pagerduty.com/enrichment/event_enrichments/{id}/associations` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. Associating an Event Orchestration or Service with an Event Enrichment allows for the enrichment to be evaluated when events are ingested for that Event Orchestration or Service > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Add new associations between an Event Enrichment and Services or Event Orchestrations. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The associations to add to the Event Enrichment. | Field | Type | Required | Description | |---|---|---|---| | `associations` | array of object | yes | | | `associations[].type` | string | | The type of the associated resource. One of: `service_reference`, `event_orchestration_reference`. | | `associations[].id` | string | | The ID of the associated Service or Event Orchestration. | | `associations[].summary` | string | | The name of the associated Service or Event Orchestration. Read-only. | | `associations[].self` | string (url) | | The API show URL at which the associated resource is accessible. Read-only. | Example: Associate a Service and an Event Orchestration ```json { "associations": [ { "type": "service_reference", "id": "PVBHKC1" }, { "type": "event_orchestration_reference", "id": "af3d4d66-4a34-46c6-9a3c-7d5d8bd8eeeb" } ] } ``` ## Response 201 Associations created successfully, or a multi-status response if some failed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | One of: `created`. | Example: All associations created successfully (201) ```json { "status": "created" } ``` Example: Partial success — some associations failed (207) ```json { "associations": [ { "status": 201, "errors": [], "association": { "type": "service_reference", "id": "PVBHKC1" } }, { "status": 500, "errors": [ "Internal Server Error" ], "association": { "type": "event_orchestration_reference", "id": "af3d4d66-4a34-46c6-9a3c-7d5d8bd8eeeb" } } ] } ``` ## Response 207 Multi-status response indicating partial success when adding or deleting associations. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `associations` | array of object | | | | `associations[].status` | integer | | The HTTP status code for this individual association attempt. | | `associations[].errors` | array of string | | Error messages for this association attempt, if any. | | `associations[].association` | object | | | | `associations[].association.type` | string | | One of: `service_reference`, `event_orchestration_reference`. | | `associations[].association.id` | string | | | Example: Partial success — some associations failed (207) ```json { "associations": [ { "status": 201, "errors": [], "association": { "type": "service_reference", "id": "PVBHKC1" } }, { "status": 500, "errors": [ "Internal Server Error" ], "association": { "type": "event_orchestration_reference", "id": "af3d4d66-4a34-46c6-9a3c-7d5d8bd8eeeb" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/create-event-enrichment # Create an Event Enrichment `POST https://api.pagerduty.com/enrichment/event_enrichments` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Create a new Event Enrichment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The Event Enrichment to create. | Field | Type | Required | Description | |---|---|---|---| | `event_enrichment` | object | yes | | | `event_enrichment.id` | string | | ID of the Event Enrichment. Read-only. | | `event_enrichment.name` | string | | The name of the Event Enrichment. | | `event_enrichment.description` | string \| null | | A description of this Event Enrichment's purpose. | | `event_enrichment.is_default` | boolean | | Indicates whether this Event Enrichment is the account default. Read-only. | | `event_enrichment.associated_services` | integer | | The number of Services associated with this Event Enrichment. Read-only. | | `event_enrichment.associated_event_orchestrations` | integer | | The number of Event Orchestrations associated with this Event Enrichment. Read-only. | | `event_enrichment.team` | object \| null | | Reference to the team that owns this Event Enrichment. | | `event_enrichment.team.id` | string | | The ID of the team. | | `event_enrichment.team.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.privileges` | object \| null | | Details about the read/update permissions of the current user for this Event Enrichment. Only present when `include[]=privileges` is requested. Read-only. | | `event_enrichment.privileges.permissions` | array of string | | The list of permissions the current user has for this Event Enrichment. | | `event_enrichment.created_at` | string (date-time) | | The date/time the Event Enrichment was created. Read-only. | | `event_enrichment.created_by` | object \| null | | Reference to the user that created the Event Enrichment. Read-only. | | `event_enrichment.created_by.id` | string | | Read-only. | | `event_enrichment.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.updated_at` | string (date-time) | | The date/time the Event Enrichment was last updated. Read-only. | | `event_enrichment.updated_by` | object \| null | | Reference to the user that last updated the Event Enrichment. Read-only. | | `event_enrichment.updated_by.id` | string | | Read-only. | | `event_enrichment.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Create a new Event Enrichment ```json { "event_enrichment": { "name": "1st Event Enrichment", "description": "My very first EE!", "team": { "id": "PA5JAKW" } } } ``` ## Response 200 The Event Enrichment was created successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event_enrichment` | object | | Same fields as `event_enrichment` above. | Example: Example Response ```json { "event_enrichment": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "name": "1st Event Enrichment", "description": "My very first EE!", "is_default": false, "associated_services": 0, "associated_event_orchestrations": 0, "team": { "id": "PA5JAKW", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PA5JAKW" }, "created_at": "2023-10-25T22:04:24Z", "created_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "updated_at": "2023-10-25T22:04:24Z", "updated_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/delete-event-enrichment # Delete an Event Enrichment `DELETE https://api.pagerduty.com/enrichment/event_enrichments/{id}` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Delete a specific Event Enrichment. The user must have "Delete" privileges for both the Event Enrichment and all of its associated items. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Event Enrichment was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/delete-event-enrichment-associations # Delete Event Enrichment associations `DELETE https://api.pagerduty.com/enrichment/event_enrichments/{id}/associations` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. Associating an Event Orchestration or Service with an Event Enrichment allows for the enrichment to be evaluated when events are ingested for that Event Orchestration or Service > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Remove associations between an Event Enrichment and Services or Event Orchestrations. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The associations to remove from the Event Enrichment. | Field | Type | Required | Description | |---|---|---|---| | `associations` | array of object | yes | | | `associations[].type` | string | | The type of the associated resource. One of: `service_reference`, `event_orchestration_reference`. | | `associations[].id` | string | | The ID of the associated Service or Event Orchestration. | | `associations[].summary` | string | | The name of the associated Service or Event Orchestration. Read-only. | | `associations[].self` | string (url) | | The API show URL at which the associated resource is accessible. Read-only. | Example: Remove a Service and an Event Orchestration association ```json { "associations": [ { "type": "service_reference", "id": "PVBHKC1" }, { "type": "event_orchestration_reference", "id": "af3d4d66-4a34-46c6-9a3c-7d5d8bd8eeeb" } ] } ``` ## Response 200 Associations deleted successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | One of: `ok`. | Example: Example Response ```json { "status": "ok" } ``` ## Response 207 Multi-status response indicating partial success when adding or deleting associations. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `associations` | array of object | | | | `associations[].status` | integer | | The HTTP status code for this individual association attempt. | | `associations[].errors` | array of string | | Error messages for this association attempt, if any. | | `associations[].association` | object | | | | `associations[].association.type` | string | | One of: `service_reference`, `event_orchestration_reference`. | | `associations[].association.id` | string | | | Example: Partial success — some associations failed (207) ```json { "associations": [ { "status": 201, "errors": [], "association": { "type": "service_reference", "id": "PVBHKC1" } }, { "status": 500, "errors": [ "Internal Server Error" ], "association": { "type": "event_orchestration_reference", "id": "af3d4d66-4a34-46c6-9a3c-7d5d8bd8eeeb" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/get-account-default-event-enrichment # Get the account default Event Enrichment `GET https://api.pagerduty.com/enrichment/event_enrichments/default` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. The default Event Enrichment gets applied to every Event Orchestration or Service that is not already associated to any other Event Enrichment > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Retrieve the account default Event Enrichment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The account default Event Enrichment. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `default` | object, nullable | | The current account default Event Enrichment. Null if no default is set. | | `default.id` | string | | The ID of the Event Enrichment. | | `default.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `default.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `default.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `previous_default` | object, nullable | | The previous account default Event Enrichment, if one was replaced. Only present after a PUT request. | | `previous_default.id` | string | | The ID of the Event Enrichment. | | `previous_default.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `previous_default.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `previous_default.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Account has a default set ```json { "default": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference", "summary": "My enrichment name", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" } } ``` Example: No default set for the account ```json { "default": null } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/get-event-enrichment # Get an Event Enrichment `GET https://api.pagerduty.com/enrichment/event_enrichments/{id}` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Retrieve details of a specific Event Enrichment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | array of string | | Include additional details. Supported value is "privileges". | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Event Enrichment object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event_enrichment` | object | | | | `event_enrichment.id` | string | | ID of the Event Enrichment. Read-only. | | `event_enrichment.name` | string | | The name of the Event Enrichment. | | `event_enrichment.description` | string \| null | | A description of this Event Enrichment's purpose. | | `event_enrichment.is_default` | boolean | | Indicates whether this Event Enrichment is the account default. Read-only. | | `event_enrichment.associated_services` | integer | | The number of Services associated with this Event Enrichment. Read-only. | | `event_enrichment.associated_event_orchestrations` | integer | | The number of Event Orchestrations associated with this Event Enrichment. Read-only. | | `event_enrichment.team` | object \| null | | Reference to the team that owns this Event Enrichment. | | `event_enrichment.team.id` | string | | The ID of the team. | | `event_enrichment.team.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.privileges` | object \| null | | Details about the read/update permissions of the current user for this Event Enrichment. Only present when `include[]=privileges` is requested. Read-only. | | `event_enrichment.privileges.permissions` | array of string | | The list of permissions the current user has for this Event Enrichment. | | `event_enrichment.created_at` | string (date-time) | | The date/time the Event Enrichment was created. Read-only. | | `event_enrichment.created_by` | object \| null | | Reference to the user that created the Event Enrichment. Read-only. | | `event_enrichment.created_by.id` | string | | Read-only. | | `event_enrichment.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.updated_at` | string (date-time) | | The date/time the Event Enrichment was last updated. Read-only. | | `event_enrichment.updated_by` | object \| null | | Reference to the user that last updated the Event Enrichment. Read-only. | | `event_enrichment.updated_by.id` | string | | Read-only. | | `event_enrichment.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Example Response ```json { "event_enrichment": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "name": "1st Event Enrichment", "description": null, "is_default": false, "associated_services": 32, "associated_event_orchestrations": 23, "team": { "id": "PA5JAKW", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PA5JAKW" }, "created_at": "2023-10-25T22:04:24Z", "created_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "updated_at": "2025-06-16T14:39:11Z", "updated_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/get-event-enrichment-rules # Get Event Enrichment rules `GET https://api.pagerduty.com/enrichment/event_enrichments/{id}/rules` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Get the rules associated with an Event Enrichment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Event Enrichment rules (orchestration path). ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | | The rules configuration for an Event Enrichment, represented as an orchestration path. | | `orchestration_path.type` | string | | The type of this orchestration path. Read-only. One of: `event_enrichment`. | | `orchestration_path.parent` | object | | Reference to the parent Event Enrichment. Read-only. | | `orchestration_path.parent.id` | string | | The ID of the Event Enrichment. | | `orchestration_path.parent.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `orchestration_path.parent.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `orchestration_path.parent.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.sets` | array of object | | An array of sets of rules. Must contain a set with id `start`. | | `orchestration_path.sets[].id` | string | | The ID of this set. The first set must have id `start`. | | `orchestration_path.sets[].rules` | array of object | | The rules in this set. | | `orchestration_path.sets[].rules[].id` | string | | The ID of this rule. Read-only. | | `orchestration_path.sets[].rules[].label` | string | | A description of this rule's purpose. | | `orchestration_path.sets[].rules[].conditions` | array of object | | Conditions that must be satisfied for this rule's actions to execute. | | `orchestration_path.sets[].rules[].conditions[].expression` | string | | A PCL condition expression. | | `orchestration_path.sets[].rules[].actions` | one of: object \| object | | Actions to perform when the rule conditions are met. Must be one of `extractions` or `enrichments`. | | `orchestration_path.sets[].rules[].actions.extractions` | array of object | yes | (Extractions) Modify the event payload using regex-based extraction or template-based composition. Maximum 25 extractions per rule. | | `orchestration_path.sets[].rules[].actions.extractions[].target` | string | | The PD-CEF field to set with the extracted value. | | `orchestration_path.sets[].rules[].actions.extractions[].template` | string \| null | | A string template used to populate the target field. Supports event field interpolation. Used for template-based extraction. | | `orchestration_path.sets[].rules[].actions.extractions[].source` | string | | The path to the event field where the regex will be applied. Used for regex-based extraction. | | `orchestration_path.sets[].rules[].actions.extractions[].regex` | string | | A RE2 regular expression. If it contains capture groups, their values are extracted and appended. If no capture groups, the whole match is used. Used for regex-based extraction. | | `orchestration_path.sets[].rules[].actions.enrichments` | array of object | yes | (Enrichments) Query a CDP enrichment schema using event values and write results back into the event payload. Maximum 1 enrichment action per rule; maximum 5 enrichment actions applied per event per Event Enrichment. | | `orchestration_path.sets[].rules[].actions.enrichments[].schema_to_search` | string | | The ID of the Enrichment Schema to query. | | `orchestration_path.sets[].rules[].actions.enrichments[].search_values` | array of object | | Configurations that specify how to read values from the event to query the Enrichment Schema. | | `orchestration_path.sets[].rules[].actions.enrichments[].target` | string | | The PD-CEF field to set with the data retrieved from the Enrichment Schema. | | `orchestration_path.sets[].rules[].disabled` | boolean | | Indicates whether the rule is disabled and would therefore not be evaluated. | | `orchestration_path.created_at` | string (date-time) | | The date/time the rules were created. Read-only. | | `orchestration_path.created_by` | object \| null | | Reference to the user that created the rules. Read-only. | | `orchestration_path.created_by.id` | string | | Read-only. | | `orchestration_path.created_by.type` | string | | Read-only. | | `orchestration_path.created_by.self` | string (url) | | Read-only. | | `orchestration_path.updated_at` | string (date-time) | | The date/time the rules were last updated. Read-only. | | `orchestration_path.updated_by` | object \| null | | Reference to the user that last updated the rules. Read-only. | | `orchestration_path.updated_by.id` | string | | Read-only. | | `orchestration_path.updated_by.type` | string | | Read-only. | | `orchestration_path.updated_by.self` | string (url) | | Read-only. | | `orchestration_path.version` | string | | Version of the rules configuration. Read-only. | Example: Example Response ```json { "orchestration_path": { "type": "event_enrichment", "parent": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4/rules", "sets": [ { "id": "start", "rules": [ { "id": "ef760c4b", "label": "Enrich events that have an `Application:` in their summary", "conditions": [ { "expression": "event.summary matches part 'Application:'" } ], "actions": { "enrichments": [ { "schema_to_search": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "search_values": [ { "path": "event.custom_details.app", "query_field_name": "app_name" } ], "target": "event.custom_details.app_metadata" } ] } } ] } ], "created_at": "2026-02-04T20:02:23Z", "created_by": { "id": "P3HAR9Y", "type": "user_reference", "self": "https://api.pagerduty.com/users/P3HAR9Y" }, "updated_at": "2026-02-10T23:53:48Z", "updated_by": null, "version": "1TpoWwY9xTKVAM2qYmiDl0kN.o9PBQDV" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/list-event-enrichment-associations # List Event Enrichment associations `GET https://api.pagerduty.com/enrichment/event_enrichments/{id}/associations` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. Associating an Event Orchestration or Service with an Event Enrichment allows for the enrichment to be evaluated when events are ingested for that Event Orchestration or Service > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Retrieve all items (Services or Event Orchestrations) associated with an Event Enrichment. If the API key lacks view access to an associated target, that item will not be returned in the results. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `association_type` | string | | Filter associations by type. Either "service" or "event_orchestration". One of: `service`, `event_orchestration`. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of associations for the Event Enrichment. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `associations` | array of object | | | | `associations[].type` | string | | The type of the associated resource. One of: `service_reference`, `event_orchestration_reference`. | | `associations[].id` | string | | The ID of the associated Service or Event Orchestration. | | `associations[].summary` | string | | The name of the associated Service or Event Orchestration. Read-only. | | `associations[].self` | string (url) | | The API show URL at which the associated resource is accessible. Read-only. | | `limit` | integer | | | | `offset` | integer | | | | `more` | boolean | | | | `total` | integer \| null | | | Example: Example Response ```json { "associations": [ { "type": "service_reference", "id": "P6NZENL", "summary": "Web Database", "self": "https://api.pagerduty.com/services/P6NZENL" }, { "type": "event_orchestration_reference", "id": "962dcc99-d338-4fd7-8454-653b2480841d", "summary": "NOC Central Ingestion", "self": "https://api.pagerduty.com/event_orchestrations/962dcc99-d338-4fd7-8454-653b2480841d" } ], "limit": 50, "offset": 0, "more": false, "total": 2 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/list-event-enrichments # List Event Enrichments `GET https://api.pagerduty.com/enrichment/event_enrichments` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Retrieve a list of all Event Enrichments in the account. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `include[]` | array of string | | Include additional details. Supported value is "privileges". | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of Event Enrichments for the account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event_enrichments` | array of object | | The list of Event Enrichments. | | `event_enrichments[].id` | string | | ID of the Event Enrichment. Read-only. | | `event_enrichments[].name` | string | | The name of the Event Enrichment. | | `event_enrichments[].description` | string \| null | | A description of this Event Enrichment's purpose. | | `event_enrichments[].is_default` | boolean | | Indicates whether this Event Enrichment is the account default. Read-only. | | `event_enrichments[].associated_services` | integer | | The number of Services associated with this Event Enrichment. Read-only. | | `event_enrichments[].associated_event_orchestrations` | integer | | The number of Event Orchestrations associated with this Event Enrichment. Read-only. | | `event_enrichments[].team` | object \| null | | Reference to the team that owns this Event Enrichment. | | `event_enrichments[].team.id` | string | | The ID of the team. | | `event_enrichments[].team.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichments[].team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichments[].privileges` | object \| null | | Details about the read/update permissions of the current user for this Event Enrichment. Only present when `include[]=privileges` is requested. Read-only. | | `event_enrichments[].privileges.permissions` | array of string | | The list of permissions the current user has for this Event Enrichment. | | `event_enrichments[].created_at` | string (date-time) | | The date/time the Event Enrichment was created. Read-only. | | `event_enrichments[].created_by` | object \| null | | Reference to the user that created the Event Enrichment. Read-only. | | `event_enrichments[].created_by.id` | string | | Read-only. | | `event_enrichments[].created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichments[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichments[].updated_at` | string (date-time) | | The date/time the Event Enrichment was last updated. Read-only. | | `event_enrichments[].updated_by` | object \| null | | Reference to the user that last updated the Event Enrichment. Read-only. | | `event_enrichments[].updated_by.id` | string | | Read-only. | | `event_enrichments[].updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichments[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichments[].self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `offset` | integer | | Echoes offset pagination property. | | `more` | boolean | | Indicates if there are additional records to return. | | `total` | integer \| null | | The total number of records matching the given query. | Example: Example Response ```json { "event_enrichments": [ { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "name": "1st Event Enrichment", "description": null, "is_default": false, "associated_services": 32, "associated_event_orchestrations": 23, "team": { "id": "PA5JAKW", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PA5JAKW" }, "created_at": "2023-10-25T22:04:24Z", "created_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "updated_at": "2025-06-16T14:39:11Z", "updated_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" } ], "limit": 25, "offset": 0, "more": false, "total": 1 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/mark-event-enrichment-as-default # Mark an Event Enrichment as the account default `PUT https://api.pagerduty.com/enrichment/event_enrichments/default` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. The default Event Enrichment gets applied to every Event Orchestration or Service that is not already associated to any other Event Enrichment > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Mark a specific Event Enrichment as the account default. Set the request body to `default: null` to clear the current default. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The Event Enrichment to set as the account default. Set to `default: null` to clear the current default. | Field | Type | Required | Description | |---|---|---|---| | `default` | object, nullable | | | | `default.id` | string | | The ID of the Event Enrichment. | | `default.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `default.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `default.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Set a new account default ```json { "default": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference" } } ``` Example: Clear the current account default ```json { "default": null } ``` ## Response 200 The updated account default Event Enrichment. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `default` | object, nullable | | The current account default Event Enrichment. Null if no default is set. | | `default.id` | string | | The ID of the Event Enrichment. | | `default.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `default.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `default.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `previous_default` | object, nullable | | The previous account default Event Enrichment, if one was replaced. Only present after a PUT request. | | `previous_default.id` | string | | The ID of the Event Enrichment. | | `previous_default.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `previous_default.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `previous_default.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: New default set, no previous default existed ```json { "default": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference", "summary": "My enrichment name", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" }, "previous_default": null } ``` Example: New default set, replacing a previous default ```json { "default": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference", "summary": "My enrichment name", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" }, "previous_default": { "id": "AGN6ZO345532XBOFCBX6OVTQ6Y", "type": "event_enrichment_reference", "summary": "The old enrichment", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN6ZO345532XBOFCBX6OVTQ6Y" } } ``` Example: Default cleared ```json { "default": null, "previous_default": { "id": "AGN6ZO345532XBOFCBX6OVTQ6Y", "type": "event_enrichment_reference", "summary": "The old enrichment", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN6ZO345532XBOFCBX6OVTQ6Y" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/update-event-enrichment # Update an Event Enrichment `PUT https://api.pagerduty.com/enrichment/event_enrichments/{id}` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Update an existing Event Enrichment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The Event Enrichment fields to update. | Field | Type | Required | Description | |---|---|---|---| | `event_enrichment` | object | yes | | | `event_enrichment.id` | string | | ID of the Event Enrichment. Read-only. | | `event_enrichment.name` | string | | The name of the Event Enrichment. | | `event_enrichment.description` | string \| null | | A description of this Event Enrichment's purpose. | | `event_enrichment.is_default` | boolean | | Indicates whether this Event Enrichment is the account default. Read-only. | | `event_enrichment.associated_services` | integer | | The number of Services associated with this Event Enrichment. Read-only. | | `event_enrichment.associated_event_orchestrations` | integer | | The number of Event Orchestrations associated with this Event Enrichment. Read-only. | | `event_enrichment.team` | object \| null | | Reference to the team that owns this Event Enrichment. | | `event_enrichment.team.id` | string | | The ID of the team. | | `event_enrichment.team.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.privileges` | object \| null | | Details about the read/update permissions of the current user for this Event Enrichment. Only present when `include[]=privileges` is requested. Read-only. | | `event_enrichment.privileges.permissions` | array of string | | The list of permissions the current user has for this Event Enrichment. | | `event_enrichment.created_at` | string (date-time) | | The date/time the Event Enrichment was created. Read-only. | | `event_enrichment.created_by` | object \| null | | Reference to the user that created the Event Enrichment. Read-only. | | `event_enrichment.created_by.id` | string | | Read-only. | | `event_enrichment.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.updated_at` | string (date-time) | | The date/time the Event Enrichment was last updated. Read-only. | | `event_enrichment.updated_by` | object \| null | | Reference to the user that last updated the Event Enrichment. Read-only. | | `event_enrichment.updated_by.id` | string | | Read-only. | | `event_enrichment.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `event_enrichment.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `event_enrichment.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Update an Event Enrichment ```json { "event_enrichment": { "name": "Event Enrichment - Updated Name", "description": "New Description", "team": { "id": "PUBG4NJ" } } } ``` ## Response 200 The updated Event Enrichment object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event_enrichment` | object | | Same fields as `event_enrichment` above. | Example: Example Response ```json { "event_enrichment": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "name": "Event Enrichment - Updated Name", "description": "New Description", "is_default": false, "associated_services": 32, "associated_event_orchestrations": 23, "team": { "id": "PUBG4NJ", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PUBG4NJ" }, "created_at": "2023-10-25T22:04:24Z", "created_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "updated_at": "2025-06-16T14:39:11Z", "updated_by": { "id": "P1TYZRY", "type": "user_reference", "self": "https://api.pagerduty.com/users/P1TYZRY" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-enrichments/update-event-enrichment-rules # Update Event Enrichment rules `PUT https://api.pagerduty.com/enrichment/event_enrichments/{id}/rules` Event Enrichments allow you to automatically add contextual data to events as they're ingested, so that relevant information is available throughout the event, alert, and incident lifecycle. By leveraging the Contextual Data Platform (CDP), you can define rules that extract values from events or query enrichment schemas to populate event fields. > ### Early Access > This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access. Update the enrichment rules for a specific Event Enrichment. Performs a full replacement of the rules set. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the Event Enrichment. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The updated Event Enrichment rules configuration. | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | The rules configuration for an Event Enrichment, represented as an orchestration path. | | `orchestration_path.type` | string | | The type of this orchestration path. Read-only. One of: `event_enrichment`. | | `orchestration_path.parent` | object | | Reference to the parent Event Enrichment. Read-only. | | `orchestration_path.parent.id` | string | | The ID of the Event Enrichment. | | `orchestration_path.parent.type` | string | | A string that determines the schema of the object. One of: `event_enrichment_reference`. | | `orchestration_path.parent.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `orchestration_path.parent.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.sets` | array of object | | An array of sets of rules. Must contain a set with id `start`. | | `orchestration_path.sets[].id` | string | | The ID of this set. The first set must have id `start`. | | `orchestration_path.sets[].rules` | array of object | | The rules in this set. | | `orchestration_path.sets[].rules[].id` | string | | The ID of this rule. Read-only. | | `orchestration_path.sets[].rules[].label` | string | | A description of this rule's purpose. | | `orchestration_path.sets[].rules[].conditions` | array of object | | Conditions that must be satisfied for this rule's actions to execute. | | `orchestration_path.sets[].rules[].conditions[].expression` | string | | A PCL condition expression. | | `orchestration_path.sets[].rules[].actions` | one of: object \| object | | Actions to perform when the rule conditions are met. Must be one of `extractions` or `enrichments`. | | `orchestration_path.sets[].rules[].actions.extractions` | array of object | yes | (Extractions) Modify the event payload using regex-based extraction or template-based composition. Maximum 25 extractions per rule. | | `orchestration_path.sets[].rules[].actions.extractions[].target` | string | | The PD-CEF field to set with the extracted value. | | `orchestration_path.sets[].rules[].actions.extractions[].template` | string \| null | | A string template used to populate the target field. Supports event field interpolation. Used for template-based extraction. | | `orchestration_path.sets[].rules[].actions.extractions[].source` | string | | The path to the event field where the regex will be applied. Used for regex-based extraction. | | `orchestration_path.sets[].rules[].actions.extractions[].regex` | string | | A RE2 regular expression. If it contains capture groups, their values are extracted and appended. If no capture groups, the whole match is used. Used for regex-based extraction. | | `orchestration_path.sets[].rules[].actions.enrichments` | array of object | yes | (Enrichments) Query a CDP enrichment schema using event values and write results back into the event payload. Maximum 1 enrichment action per rule; maximum 5 enrichment actions applied per event per Event Enrichment. | | `orchestration_path.sets[].rules[].actions.enrichments[].schema_to_search` | string | | The ID of the Enrichment Schema to query. | | `orchestration_path.sets[].rules[].actions.enrichments[].search_values` | array of object | | Configurations that specify how to read values from the event to query the Enrichment Schema. | | `orchestration_path.sets[].rules[].actions.enrichments[].target` | string | | The PD-CEF field to set with the data retrieved from the Enrichment Schema. | | `orchestration_path.sets[].rules[].disabled` | boolean | | Indicates whether the rule is disabled and would therefore not be evaluated. | | `orchestration_path.created_at` | string (date-time) | | The date/time the rules were created. Read-only. | | `orchestration_path.created_by` | object \| null | | Reference to the user that created the rules. Read-only. | | `orchestration_path.created_by.id` | string | | Read-only. | | `orchestration_path.created_by.type` | string | | Read-only. | | `orchestration_path.created_by.self` | string (url) | | Read-only. | | `orchestration_path.updated_at` | string (date-time) | | The date/time the rules were last updated. Read-only. | | `orchestration_path.updated_by` | object \| null | | Reference to the user that last updated the rules. Read-only. | | `orchestration_path.updated_by.id` | string | | Read-only. | | `orchestration_path.updated_by.type` | string | | Read-only. | | `orchestration_path.updated_by.self` | string (url) | | Read-only. | | `orchestration_path.version` | string | | Version of the rules configuration. Read-only. | Example: Update rules with an extraction action ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Extract server name from event source", "conditions": [ { "expression": "event.summary matches part 'Application:'" } ], "actions": { "extractions": [ { "target": "event.custom_details.server_name", "template": "[production] {{event.source}}" } ] } } ] } ] } } ``` Example: Update rules with an enrichment action ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Enrich events that have an `Application:` in their summary", "conditions": [ { "expression": "event.summary matches part 'Application:'" } ], "actions": { "enrichments": [ { "schema_to_search": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821", "search_values": [ { "path": "event.custom_details.app", "query_field_name": "app_name" } ], "target": "event.custom_details.app_metadata" } ] } } ] } ] } } ``` ## Response 200 The updated Event Enrichment rules (orchestration path). ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | | The rules configuration for an Event Enrichment, represented as an orchestration path. Same fields as `orchestration_path` above. | Example: Example Response ```json { "orchestration_path": { "type": "event_enrichment", "parent": { "id": "AGN4PVDO2F5AZIVWETZ42I6IP4", "type": "event_enrichment_reference", "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4" }, "self": "https://api.pagerduty.com/enrichment/event_enrichments/AGN4PVDO2F5AZIVWETZ42I6IP4/rules", "sets": [ { "id": "start", "rules": [ { "id": "ef760c4b", "label": "Extract server name from event source", "conditions": [ { "expression": "event.summary matches part 'Application:'" } ], "actions": { "extractions": [ { "target": "event.custom_details.server_name", "template": "[production] {{event.source}}", "source": null, "regex": null } ] } } ] } ], "created_at": "2026-02-04T20:02:23Z", "created_by": { "id": "P3HAR9Y", "type": "user_reference", "self": "https://api.pagerduty.com/users/P3HAR9Y" }, "updated_at": "2026-02-10T23:53:48Z", "updated_by": { "id": "P3HAR9Y", "type": "user_reference", "self": "https://api.pagerduty.com/users/P3HAR9Y" }, "version": "2UqpXzY0aULBen3DisjGm1lQ.p0QDVE" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/create-cache-var-on-global-orch # Create a Cache Variable for a Global Event Orchestration `POST https://api.pagerduty.com/event_orchestrations/{id}/cache_variables` Create a Cache Variable for a Global Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | yes | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Request Example: Recent value cache variable ```json { "cache_variable": { "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" } } } ``` Example: Request Example: Trigger event count cache variable ```json { "cache_variable": { "name": "example_2", "configuration": { "type": "trigger_event_count", "ttl_seconds": 30 } } } ``` Example: Request Example: External Data cache variable ```json { "cache_variable": { "name": "example_3", "configuration": { "type": "external_data", "ttl_seconds": 300, "data_type": "boolean" } } } ``` ## Response 200 The created Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example: Recent value cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Trigger event count cache variable ```json { "cache_variable": [ { "id": "f08cdd8d-10a5-4c70-b508-82ab5c365a43", "name": "example_2", "conditions": [], "configuration": { "type": "trigger_event_count", "ttl_seconds": 30 }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: External data cache variable ```json { "cache_variable": [ { "id": "d35f6e12-c391-4606-93b8-2b7295670077", "name": "example_3", "configuration": { "type": "external_data", "ttl_seconds": 300, "data_type": "boolean" }, "created_at": "2021-11-18T16:43:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:43:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "data_endpoint": "https://api.pagerduty.com/event_orchestrations/e5b42543-c10d-460d-8581-e89f08e0dcae/cache_variables/d35f6e12-c391-4606-93b8-2b7295670077/data" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/create-cache-var-on-service-orch # Create a Cache Variable for a Service Event Orchestration `POST https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables` Create a Cache Variable for a Service Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | yes | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Request Example: Recent value cache variable ```json { "cache_variable": { "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" } } } ``` Example: Request Example: Trigger event count cache variable ```json { "cache_variable": { "name": "example_2", "configuration": { "type": "trigger_event_count", "ttl_seconds": 30 } } } ``` Example: Request Example: External Data cache variable ```json { "cache_variable": { "name": "example_3", "configuration": { "type": "external_data", "ttl_seconds": 300, "data_type": "boolean" } } } ``` ## Response 200 The created Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example: Recent value cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Trigger event count cache variable ```json { "cache_variable": [ { "id": "f08cdd8d-10a5-4c70-b508-82ab5c365a43", "name": "example_2", "conditions": [], "configuration": { "type": "trigger_event_count", "ttl_seconds": 30 }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: External data cache variable ```json { "cache_variable": [ { "id": "d35f6e12-c391-4606-93b8-2b7295670077", "name": "example_3", "configuration": { "type": "external_data", "ttl_seconds": 300, "data_type": "boolean" }, "created_at": "2021-11-18T16:43:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:43:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "data_endpoint": "https://api.pagerduty.com/event_orchestrations/e5b42543-c10d-460d-8581-e89f08e0dcae/cache_variables/d35f6e12-c391-4606-93b8-2b7295670077/data" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-cache-var-on-global-orch # Delete a Cache Variable for a Global Event Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}` Delete a Cache Variable for a Global Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Cache Variable was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-cache-var-on-service-orch # Delete a Cache Variable for a Service Event Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}` Delete a Cache Variable for a Service Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Cache Variable was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-external-data-cache-var-data-on-global-orch # Delete Data for an External Data Cache Variable on a Global Event Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}/data` Delete data for an `external_data` type Cache Variable on a Global Event Orchestration Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Data was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-external-data-cache-var-data-on-service-orch # Delete Data for an External Data Cache Variable on a Service Event Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}/data` Delete Data for an `external_data` type Cache Variable on a Service Event Orchestration. Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Data was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-orchestration # Delete an Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/{id}` Delete a Global Event Orchestration. Once deleted, you will no longer be able to ingest events into PagerDuty using this Orchestration's Routing Key. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Orchestration was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/delete-orchestration-integration # Delete an Integration for an Event Orchestration `DELETE https://api.pagerduty.com/event_orchestrations/{id}/integrations/{integration_id}` Delete an Integration and its associated Routing Key. Once deleted, PagerDuty will drop all future events sent to PagerDuty using the Routing Key. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `integration_id` | string | yes | The ID of an Integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Integration was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-cache-var-on-global-orch # Get a Cache Variable for a Global Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}` Get a Cache Variable for a Global Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The fetched Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example ```json { "cache_variable": [ { "id": "64122e97-de81-4554-9d7c-c219cef351cd", "name": "cache_var_1", "conditions": [ { "expression": "raw_event.class exists and event.summary matches part 'unstable'" } ], "configuration": { "type": "recent_value", "source": "event.custom_details.work_id", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-cache-var-on-service-orch # Get a Cache Variable for a Service Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}` Get a Cache Variable for a Service Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The fetched Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example ```json { "cache_variable": [ { "id": "64122e97-de81-4554-9d7c-c219cef351cd", "name": "cache_var_1", "conditions": [ { "expression": "raw_event.class exists and event.summary matches part 'unstable'" } ], "configuration": { "type": "recent_value", "source": "event.custom_details.work_id", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-external-data-cache-var-data-on-global-orch # Get Data for an External Data Cache Variable on a Global Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}/data` Get the data for an `external_data` type Cache Variable on a Global Orchestration. Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The data on an `external_data` type Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Response Example: String data ```json { "cache_variable_data": "Hello World!", "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Number data ```json { "cache_variable_data": 45.348, "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Boolean data ```json { "cache_variable_data": true, "updated_at": "2021-11-18T16:42:01Z" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-external-data-cache-var-data-on-service-orch # Get Data for an External Data Cache Variable on a Service Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}/data` Get the data for an `external_data` type Cache Variable for a Service Event Orchestration. Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The data on an `external_data` type Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Response Example: String data ```json { "cache_variable_data": "Hello World!", "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Number data ```json { "cache_variable_data": 45.348, "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Boolean data ```json { "cache_variable_data": true, "updated_at": "2021-11-18T16:42:01Z" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orch-active-status # Get the Service Orchestration active status for a Service `GET https://api.pagerduty.com/event_orchestrations/services/{service_id}/active` Get a Service Orchestration's active status. A Service Orchestration allows you to set an active status based on whether an event will be evaluated against a service orchestration path (true) or service ruleset (false). For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An object with the active status. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | The status of the service orchestration. | Example: Example Response ```json { "active": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orch-path-global # Get the Global Orchestration for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/global` Get the Global Orchestration for an Event Orchestration. Global Orchestration Rules allows you to create a set of Event Rules. These rules evaluate against all Events sent to an Event Orchestration. When a matching rule is found, it can modify and enhance the event and can route the event to another set of Global Rules within this Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Global Orchestration Rules object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a set of "global" rules. Default: `global`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration these Global Rules belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | You must define at least a "start" set, but you can also define any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.drop_event` | boolean | | If true, this event will be dropped. Dropped events will not trigger or resolve an alert or an incident. Dropped events will not be evaluated against router rules. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | Example: Example Response ```json { "orchestration_path": { "type": "global", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/global", "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to all events", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ], "route_to": "step-two" } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "Drop all events from the very-noisy monitoring tool", "id": "1f6d9a33", "conditions": [ { "expression": "event.source matches part 'very-noisy'" } ], "actions": { "drop_event": true } }, { "label": "Assign all database related incidents to the Database Team's escalation policy", "id": "4314d9ce", "conditions": [ { "expression": "event.source matches 'prod-db'" } ], "actions": { "escalation_policy": "PEYSGVF" } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "rn1Mja13T1HBdmPChqFilSQXUW2fWXM_" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orch-path-router # Get the Router for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/router` Get a Global Orchestration's Routing Rules. An Orchestration Router allows you to create a set of Event Rules. The Router evaluates Events you send to this Global Orchestration against each of its rules, one at a time, and routes the event to a specific Service based on the first rule that matches. If an event doesn't match any rules, it'll be sent to service specified in as the `catch_all` or the "Unrouted" Orchestration if no service is specified. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Orchestration Router object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "router" type set of rules. Default: `router`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Router belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | The Router contains a single set of rules (the "start" set). The Router evaluates Events against these Rules, one at a time, and routes each Event to a specific Service based on the first rule that matches. Min items: 1. Max items: 1. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.route_to` | string | | With a value of 'unrouted', all events are sent to the Unrouted Orchestration. Default: `unrouted`. | Example: Example Response ```json { "orchestration_path": { "type": "router", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/router", "sets": [ { "id": "start", "rules": [ { "label": "Events relating to our relational database", "id": "1c26698b", "conditions": [ { "expression": "event.summary matches part 'database'" }, { "expression": "event.source matches regex 'db[0-9]+-server'" } ], "actions": { "route_to": "PB31XBA" } }, { "label": "Events relating to our www app server", "id": "d9801904", "conditions": [ { "expression": "event.summary matches part 'www'" } ], "actions": { "route_to": "PC2D9ML" } } ] } ], "catch_all": { "actions": { "route_to": "unrouted" } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "9co0z4b152oICsoV91_PW2.ww8ip_xap" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orch-path-service # Get the Service Orchestration for a Service `GET https://api.pagerduty.com/event_orchestrations/services/{service_id}` Get a Service Orchestration. A Service Orchestration allows you to create a set of Event Rules. The Service Orchestration evaluates Events sent to this Service against each of its rules, beginning with the rules in the "start" set. When a matching rule is found, it can modify and enhance the event and can route the event to another set of rules within this Service Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. One of: `migrated_metadata`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Service Orchestration object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.migrated_at` | string (date-time) | | The date/time the service's Event Rules were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by` | object | | Reference to the user that converted the service's Event Rules to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by.id` | string | | Read-only. | | `orchestration_path.migrated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_from` | object | | Reference to the Service Event Rules that were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_from.id` | string | | Read-only. | | `orchestration_path.migrated_from.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_from.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_status` | string | | The status indicating whether the service's Event Rules were successfully converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `completed`. | | `orchestration_path.migrated_via` | string | | Indicates whether the conversion was performed via the PagerDuty API or PagerDuty website. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `API`, `UI`. | | `orchestration_path.type` | | | Indicates that these are sets of rules belonging to a service. Default: `service`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | The ID of the Service this Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `service_reference`. | | `orchestration_path.sets` | | | A Service Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions` | array of object | | Configure an Automation Action to be run for certain alert states. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].action_id` | string | | Automation Action ID. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].trigger_types` | array of string | | The Automation Action will be triggered whenever an alert reaches the specified state. Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | Example: Example Response ```json { "orchestration_path": { "type": "service", "parent": { "id": "PC2D9ML", "self": "https://api.pagerduty.com/service/PC2D9ML", "type": "service_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/service/PC2D9ML", "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to every event sent to this Service", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "pagerduty_automation_actions": [ { "action_id": "01CSB5SMOKCKVRI5GN0LJG7SMB", "trigger_types": [ "alert_triggered" ] } ], "route_to": "step-two", "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ] } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "annotate": "Please use our P1 runbook: https://docs.test/p1-runbook", "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "If there's something wrong on the canary let the team know about it in our deployments Slack channel", "id": "1f6d9a33", "conditions": [ { "expression": "event.custom_details.hostname matches part 'canary'" } ], "actions": { "automation_actions": [ { "name": "Canary Slack Notification", "url": "https://our-slack-listerner.test/send-notification", "auto_send": true, "headers": [ { "key": "X-Notification-Source", "value": "PagerDuty Incident Webhook" } ], "parameters": [ { "key": "channel", "value": "#my-team-channel" }, { "key": "message", "value": "Something is wrong with the canary deployment" } ], "trigger_types": [ "alert_triggered" ] } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" } ] } }, { "label": "Pause the alert and trigger a reboot action if flaky server receives an error", "id": "c0163dbe", "conditions": [ { "expression": "event.custom_details.hostname matches part 'staging'" } ], "actions": { "suspend": 300, "pagerduty_automation_actions": [ { "action_id": "01CSBCGJXMG7ABIJZKPD8P9RCL", "trigger_types": [ "alert_suspended" ] } ] } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "migrated_at": "2023-06-14T13:51:31Z", "migrated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "migrated_from": { "id": "PC2D9ML", "self": "https://api.pagerduty.com/services/PC2D9ML/rules", "type": "service_event_rules_reference" }, "migrated_status": "completed", "migrated_via": "UI", "version": "rn1Mja13T1HBdmPChqFilSQXUW2fWXM_" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orch-path-unrouted # Get the Unrouted Orchestration for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/unrouted` Get a Global Event Orchestration's Rules for Unrouted events. An Unrouted Orchestration allows you to create a set of Event Rules that will be evaluated against all events that don't match any rules in the Global Orchestration's Router. Events that reach the Unrouted Orchestration will never be routed to a specific Service. The Unrouted Orchestration evaluates Events sent to it against each of its rules, beginning with the rules in the "start" set. When a matching rule is found, it can modify and enhance the event and can route the event to another set of rules within this Unrouted Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Unrouted Orchestration object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "unrouted" type set of rules. Default: `unrouted`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Unrouted Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | An Unrouted Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | Example: Example Response ```json { "orchestration_path": { "type": "unrouted", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/router", "sets": [ { "id": "start", "rules": [ { "label": "Update the summary of un-matched Critical alerts so they're easier to spot", "id": "38880ffb", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "extractions": [ { "target": "event.summary", "template": "[Critical Unrouted] {{event.summary}}" } ] } }, { "label": "Reduce the severity of all other unrouted events", "id": "3896801e", "conditions": [], "actions": { "severity": "info" } } ] } ], "catch_all": { "actions": { "suppress": true } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "aZO.EEf9zWb9Vg0NYq.Uqad1hOC2Maod" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orchestration # Get an Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}` Get a Global Event Orchestration. Global Event Orchestrations allow you define a set of Global Rules and Router Rules, so that when you ingest events using the Orchestration's Routing Key your events will have actions applied via the Global Rules & then routed to the correct Service by the Router Rules, based on the event's content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Orchestration object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration` | object | | | | `orchestration.id` | string | | ID of the Orchestration. Read-only. | | `orchestration.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.name` | string | | Name of the Orchestration. | | `orchestration.description` | string | | A description of this Orchestration's purpose. | | `orchestration.team` | object | | Reference to the team that owns the Orchestration. If none is specified, only admins have access. | | `orchestration.team.id` | string | | | | `orchestration.team.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.integrations` | array of object | | Read-only. | | `orchestration.integrations[].id` | string | | ID of the Integration. Read-only. | | `orchestration.integrations[].label` | string | | Name of the Integration. | | `orchestration.integrations[].parameters` | object | | Read-only. | | `orchestration.integrations[].parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `orchestration.integrations[].parameters.type` | string | | Read-only. Default: `global`. | | `orchestration.routes` | integer | | Number of different Service Orchestration being routed to. Read-only. | | `orchestration.created_at` | string (date-time) | | The date the Orchestration was created at. Read-only. | | `orchestration.created_by` | object | | Reference to the user that has created the Orchestration. Read-only. | | `orchestration.created_by.id` | string | | Read-only. | | `orchestration.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.updated_at` | string (date-time) | | The date the Orchestration was last updated. Read-only. | | `orchestration.updated_by` | object | | Reference to the user that has updated the Orchestration last. Read-only. | | `orchestration.updated_by.id` | string | | Read-only. | | `orchestration.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.version` | string | | Version of the Orchestration. Read-only. | Example: Response Example ```json { "orchestration": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "name": "Shopping Cart Orchestration", "description": "Send shopping cart alerts to the right services", "team": { "id": "PQYP5MN", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PQYP5MN" }, "integrations": [ { "id": "9c5ff030-12da-4204-a067-25ee61a8df6c", "label": "Shopping Cart Orchestration Default Integration", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } ], "routes": 0, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "9co0z4b152oICsoV91_PW2.ww8ip_xap" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/get-orchestration-integration # Get an Integration for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/integrations/{integration_id}` Get an Integration associated with this Event Orchestrations. You can use the Routing Key from this Integration to send events to PagerDuty! For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `integration_id` | string | yes | The ID of an Integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An Integration for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | | | | `integration.id` | string | | ID of the Integration. Read-only. | | `integration.label` | string | | Name of the Integration. | | `integration.parameters` | object | | Read-only. | | `integration.parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `integration.parameters.type` | string | | Read-only. Default: `global`. | Example: Response Example ```json { "integration": { "id": "9c5ff030-12da-4204-a067-25ee61a8df6c", "label": "Go-Kart Orchestration Default Integration", "parameters": { "routing_key": "R022XIJR9M266DX570EVE6EXP1AFBN6D", "type": "global" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/list-cache-var-on-global-orch # List Cache Variables for a Global Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/cache_variables` List Cache Variables for a Global Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Cache Variables for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variables` | array of one of: object \| object \| object | | | | `cache_variables[].id` | string | | (Recent Value) Read-only. | | `cache_variables[].name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (Recent Value) | | `cache_variables[].configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variables[].configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variables[].configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variables[].conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variables[].conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variables[].id` | string | | (Trigger Event Count) Read-only. | | `cache_variables[].name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (Trigger Event Count) | | `cache_variables[].configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variables[].configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variables[].conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variables[].conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variables[].id` | string | | (External Data) Read-only. | | `cache_variables[].name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (External Data) | | `cache_variables[].configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variables[].configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variables[].configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variables[].data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example ```json { "cache_variables": [ { "id": "294c3ee9-ae83-4da7-828d-107c71dc9316", "name": "cache_var_1", "conditions": [ { "expression": "event.source exists" }, { "expression": "event.severity matches 'critical'" } ], "configuration": { "type": "recent_value", "source": "event.source", "regex": "www (.*) service" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } }, { "id": "2a6d02d5-6365-4326-aaf1-6a719e990245", "name": "cache_var_2", "conditions": [], "configuration": { "type": "trigger_event_count", "ttl_seconds": 60 }, "disabled": true, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } }, { "id": "b910c789-5b47-4635-a23c-20a5578b3e9a", "name": "cache_var_3", "configuration": { "type": "external_data", "ttl_seconds": 500 }, "disabled": false, "data_endpoint": "https://api.pagerduty.com/event_orchestrations/e5b42543-c10d-460d-8581-e89f08e0dcae/cache_variables/b910c789-5b47-4635-a23c-20a5578b3e9a/data", "created_at": "2024-10-03T16:28:48Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ], "total": 3 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/list-cache-var-on-service-orch # List Cache Variables for a Service Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables` List Cache Variables for a Service Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Cache Variables for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variables` | array of one of: object \| object \| object | | | | `cache_variables[].id` | string | | (Recent Value) Read-only. | | `cache_variables[].name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (Recent Value) | | `cache_variables[].configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variables[].configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variables[].configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variables[].conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variables[].conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variables[].id` | string | | (Trigger Event Count) Read-only. | | `cache_variables[].name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (Trigger Event Count) | | `cache_variables[].configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variables[].configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variables[].conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variables[].conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variables[].id` | string | | (External Data) Read-only. | | `cache_variables[].name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variables[].disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variables[].created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variables[].created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variables[].created_by.id` | string | | Read-only. | | `cache_variables[].created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variables[].updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variables[].updated_by.id` | string | | Read-only. | | `cache_variables[].updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variables[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variables[].configuration` | object | yes | (External Data) | | `cache_variables[].configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variables[].configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variables[].configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variables[].data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example ```json { "cache_variables": [ { "id": "294c3ee9-ae83-4da7-828d-107c71dc9316", "name": "cache_var_1", "conditions": [ { "expression": "event.source exists" }, { "expression": "event.severity matches 'critical'" } ], "configuration": { "type": "recent_value", "source": "event.source", "regex": "www (.*) service" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } }, { "id": "2a6d02d5-6365-4326-aaf1-6a719e990245", "name": "cache_var_2", "conditions": [], "configuration": { "type": "trigger_event_count", "ttl_seconds": 60 }, "disabled": true, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } }, { "id": "b910c789-5b47-4635-a23c-20a5578b3e9a", "name": "cache_var_3", "configuration": { "type": "external_data", "ttl_seconds": 500 }, "disabled": false, "data_endpoint": "https://api.pagerduty.com/event_orchestrations/e5b42543-c10d-460d-8581-e89f08e0dcae/cache_variables/b910c789-5b47-4635-a23c-20a5578b3e9a/data", "created_at": "2024-10-03T16:28:48Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ], "total": 3 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/list-event-orchestration-feature-enablements # List Enablements for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/enablements` List all feature enablement settings for an Event Orchestration. Currently, only the `aiops` enablement is supported. For any account with the AIOps product addon, every Event Orchestration will have AIOps features enabled by default. **Warning conditions**: - If the account is not entitled to use AIOps features, a warning will be returned alongside the enablement data. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The list of feature enablement settings for the Event Orchestation. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `enablements` | array of object | | Array of feature enablement settings. | | `enablements[].feature` | string | | The name of the product addon whose set of features will be enabled or disabled. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Read-only. | | `enablements[].enabled` | boolean | yes | A boolean value indicating whether the specified product addon is enabled or disabled. | | `enablements[].updated_at` | string (date-time) | | The time the feature enablement was last updated. Read-only. | | `enablements[].warnings` | array of object | | An array of warnings related to this feature enablement. Only present if warning conditions are met. Read-only. | | `enablements[].warnings[].message` | string | | The warning message. | Example: Success Response ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z" } ] } ``` Example: Response with No Entitlement Warning ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z", "warnings": [ { "message": "You can't use AIOps functionality with this Orchestration because your account hasn't purchased AIOps" } ] } ] } ``` Example: Default Response (No Settings Configured) ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": null } ] } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/list-event-orchestrations # List Event Orchestrations `GET https://api.pagerduty.com/event_orchestrations` List all Global Event Orchestrations on an Account. Global Event Orchestrations allow you define a set of Global Rules and Router Rules, so that when you ingest events using the Orchestration's Routing Key your events will have actions applied via the Global Rules & then routed to the correct Service by the Router Rules, based on the event's content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `sort_by` | string | | Used to specify the field you wish to sort the results on. One of: `name:asc`, `name:desc`, `routes:asc`, `routes:desc`, `created_at:asc`, `created_at:desc`. Default: `name:asc`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Event Orchestration objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `orchestrations` | array of object | | | | `orchestrations[].id` | string | | ID of the Orchestration. Read-only. | | `orchestrations[].self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestrations[].name` | string | | Name of the Orchestration. | | `orchestrations[].description` | string | | A description of this Orchestration's purpose. | | `orchestrations[].team` | object | | Reference to the team that owns the Orchestration. If none is specified, only admins have access. | | `orchestrations[].team.id` | string | | | | `orchestrations[].team.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestrations[].team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestrations[].routes` | integer | | Number of different Service Orchestration being routed to. Read-only. | | `orchestrations[].created_at` | string (date-time) | | The date the Orchestration was created at. Read-only. | | `orchestrations[].created_by` | object | | Reference to the user that has created the Orchestration. Read-only. | | `orchestrations[].created_by.id` | string | | Read-only. | | `orchestrations[].created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestrations[].created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestrations[].updated_at` | string (date-time) | | The date the Orchestration was last updated. Read-only. | | `orchestrations[].updated_by` | object | | Reference to the user that has updated the Orchestration last. Read-only. | | `orchestrations[].updated_by.id` | string | | Read-only. | | `orchestrations[].updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestrations[].updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestrations[].version` | string | | Version of the Orchestration. Read-only. | Example: Response Example ```json { "orchestrations": [ { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "name": "Shopping Cart Orchestration", "description": "Send shopping cart alerts to the right services", "team": { "id": "PQYP5MN", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PQYP5MN" }, "routes": 0, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "9co0z4b152oICsoV91_PW2.ww8ip_xap" } ], "limit": 25, "offset": 0, "more": false, "total": 1 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/list-orchestration-integrations # List Integrations for an Event Orchestration `GET https://api.pagerduty.com/event_orchestrations/{id}/integrations` List the Integrations associated with this Event Orchestrations. You can use a Routing Key from these Integrations to send events to PagerDuty! For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Integrations for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integrations` | array of object | | | | `integrations[].id` | string | | ID of the Integration. Read-only. | | `integrations[].label` | string | | Name of the Integration. | | `integrations[].parameters` | object | | Read-only. | | `integrations[].parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `integrations[].parameters.type` | string | | Read-only. Default: `global`. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | Example: Response Example ```json { "integrations": [ { "id": "9c5ff030-12da-4204-a067-25ee61a8df6c", "label": "Go-Kart Orchestration Default Integration", "parameters": { "routing_key": "R022XIJR9M266DX570EVE6EXP1AFBN6D", "type": "global" } }, { "id": "11832872-88b6-4661-8972-db5712b69496", "label": "Integration for Monitoring Tool X", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } ], "total": 2 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/migrate-orchestration-integration # Migrate an Integration from one Event Orchestration to another `POST https://api.pagerduty.com/event_orchestrations/{id}/integrations/migration` Move an Integration and its Routing Key from the Event Orchestration specified in the request payload, to the Event Orchestration specified in the request URL. Any future events sent to this Integration's Routing Key will be processed by this Event Orchestration's Rules. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `source_id` | string | yes | The ID of the Event Orchestration you'll be moving the Integration away from. | | `source_type` | string | yes | The type of of the `source_id` object. One of: `orchestration`. | | `integration_id` | string | yes | The ID of the Integration you'll be moving. | Example: Example: Migrate an Integration ```json { "source_type": "orchestration", "source_id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "integration_id": "11832872-88b6-4661-8972-db5712b69496" } ``` ## Response 200 The Integration that was migrated ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integrations` | array of object | | | | `integrations[].id` | string | | ID of the Integration. Read-only. | | `integrations[].label` | string | | Name of the Integration. | | `integrations[].parameters` | object | | Read-only. | | `integrations[].parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `integrations[].parameters.type` | string | | Read-only. Default: `global`. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | Example: Response Example ```json { "integrations": [ { "id": "9c5ff030-12da-4204-a067-25ee61a8df6c", "label": "Go-Kart Orchestration Default Integration", "parameters": { "routing_key": "R022XIJR9M266DX570EVE6EXP1AFBN6D", "type": "global" } }, { "id": "11832872-88b6-4661-8972-db5712b69496", "label": "Integration for Monitoring Tool X", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } ], "total": 2 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/post-orchestration # Create an Orchestration `POST https://api.pagerduty.com/event_orchestrations` Create a Global Event Orchestration. Global Event Orchestrations allow you define a set of Global Rules and Router Rules, so that when you ingest events using the Orchestration's Routing Key your events will have actions applied via the Global Rules & then routed to the correct Service by the Router Rules, based on the event's content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `orchestration` | object | yes | | | `orchestration.id` | string | | ID of the Orchestration. Read-only. | | `orchestration.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.name` | string | | Name of the Orchestration. | | `orchestration.description` | string | | A description of this Orchestration's purpose. | | `orchestration.team` | object | | Reference to the team that owns the Orchestration. If none is specified, only admins have access. | | `orchestration.team.id` | string | | | | `orchestration.team.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.integrations` | array of object | | Read-only. | | `orchestration.integrations[].id` | string | | ID of the Integration. Read-only. | | `orchestration.integrations[].label` | string | | Name of the Integration. | | `orchestration.integrations[].parameters` | object | | Read-only. | | `orchestration.integrations[].parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `orchestration.integrations[].parameters.type` | string | | Read-only. Default: `global`. | | `orchestration.routes` | integer | | Number of different Service Orchestration being routed to. Read-only. | | `orchestration.created_at` | string (date-time) | | The date the Orchestration was created at. Read-only. | | `orchestration.created_by` | object | | Reference to the user that has created the Orchestration. Read-only. | | `orchestration.created_by.id` | string | | Read-only. | | `orchestration.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.updated_at` | string (date-time) | | The date the Orchestration was last updated. Read-only. | | `orchestration.updated_by` | object | | Reference to the user that has updated the Orchestration last. Read-only. | | `orchestration.updated_by.id` | string | | Read-only. | | `orchestration.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.version` | string | | Version of the Orchestration. Read-only. | Example: Example: Create Orchestration ```json { "orchestration": { "name": "New Orchestration", "description": "This is a newly created orchestration", "team": { "id": "PXD0WR8" } } } ``` ## Response 201 The Orchestration that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration` | object | | Same fields as `orchestration` above. | Example: Response Example ```json { "orchestration": { "id": "3aae9a17-8585-4d8c-93d3-99742801cd95", "self": "https://api.pagerduty.com/event_orchestrations/3aae9a17-8585-4d8c-93d3-99742801cd95", "name": "New Orchestration", "description": "This is a newly created orchestration", "team": { "id": "PXD0WR8", "self": "https://api.pagerduty.com/teams/PXD0WR8", "type": "team_reference" }, "integrations": [ { "id": "461cd942-d7cc-43ef-ac7d-86ba2d58fc45", "label": "New Orchestration Default Integration", "parameters": { "routing_key": "R022XIJR9M266DX570EVE6EXP1AFBN6D", "type": "global" } } ], "routes": 0, "created_at": "2021-12-02T14:21:42Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-12-02T14:21:42Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "oBgzJsGDOz99G.FKZ0c1C6hw35twk_Ib" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/post-orchestration-integration # Create an Integration for an Event Orchestration `POST https://api.pagerduty.com/event_orchestrations/{id}/integrations` Create an Integration associated with this Event Orchestration. You can then use the Routing Key from this new Integration to send events to PagerDuty! For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | | | `integration.label` | string | yes | Name of the Integration. | Example: Example: Create an Integration ```json { "integration": { "label": "Integration for Monitoring Tool X" } } ``` ## Response 201 The Integration that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | | | | `integration.id` | string | | ID of the Integration. Read-only. | | `integration.label` | string | | Name of the Integration. | | `integration.parameters` | object | | Read-only. | | `integration.parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `integration.parameters.type` | string | | Read-only. Default: `global`. | Example: Response Example ```json { "integration": { "id": "11832872-88b6-4661-8972-db5712b69496", "label": "Integration for Monitoring Tool X", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-cache-var-on-global-orch # Update a Cache Variable for a Global Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}` Update a Cache Variable for a Global Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | yes | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Request Example: Update conditions (trigger_event_count, recent_value) ```json { "cache_variable": { "name": "example_1", "conditions": [ { "expression": "event.summary matches 'exception'" }, { "expression": "event.summary matches 'error'" } ] } } ``` Example: Request Example: Update configuration ```json { "cache_variable": { "name": "example_1", "configuration": { "type": "trigger_event_count", "ttl_seconds": 2 } } } ``` Example: Request Example: Update disabled state ```json { "cache_variable": { "name": "example_1", "disabled": true } } ``` ## Response 200 The updated Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example: Recent value cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "event.summary matches 'exception'" }, { "expression": "event.summary matches 'error'" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Trigger event count cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "trigger_event_count", "ttl_seconds": 2 }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Disabled cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "disabled": true, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-cache-var-on-service-orch # Update a Cache Variable for a Service Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}` Update a Cache Variable for a Service Event Orchestration. Cache Variables allow you to store event data on an Event Orchestration, which can then be used in Event Orchestration rules as part of conditions or actions. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | yes | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Request Example: Update conditions (trigger_event_count, recent_value) ```json { "cache_variable": { "name": "example_1", "conditions": [ { "expression": "event.summary matches 'exception'" }, { "expression": "event.summary matches 'error'" } ] } } ``` Example: Request Example: Update configuration ```json { "cache_variable": { "name": "example_1", "configuration": { "type": "trigger_event_count", "ttl_seconds": 2 } } } ``` Example: Request Example: Update disabled state ```json { "cache_variable": { "name": "example_1", "disabled": true } } ``` ## Response 200 The updated Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable` | one of: object \| object \| object | | | | `cache_variable.id` | string | | (Recent Value) Read-only. | | `cache_variable.name` | string | yes | (Recent Value) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Recent Value) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Recent Value) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Recent Value) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Recent Value) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Recent Value) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Recent Value) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the most recent value seen, based on the source event field and the extraction regex specified. One of: `recent_value`. | | `cache_variable.configuration.source` | string | | The path to the event field where the regex will be applied to extract a value. | | `cache_variable.configuration.regex` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `cache_variable.conditions` | array of object | | (Recent Value) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (Trigger Event Count) Read-only. | | `cache_variable.name` | string | yes | (Trigger Event Count) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (Trigger Event Count) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (Trigger Event Count) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (Trigger Event Count) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (Trigger Event Count) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (Trigger Event Count) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (Trigger Event Count) | | `cache_variable.configuration.type` | string | | Cache Variable will be set to the number of trigger events that have been seen within the TTL range. One of: `trigger_event_count`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long to count trigger events before resetting back to 0. | | `cache_variable.conditions` | array of object | | (Trigger Event Count) Each of these conditions is evaluated to check if an event matches this rule. The rule is considered a match if **any** of these conditions match. | | `cache_variable.conditions[].expression` | string | | A PCL condition string. Note: The `trigger_count` and `resetting_trigger_count` operators are unsupported for Cache Variables. | | `cache_variable.id` | string | | (External Data) Read-only. | | `cache_variable.name` | string | yes | (External Data) The name of the Cache Variable. | | `cache_variable.disabled` | boolean | | (External Data) Indicates whether the Cache Variable is disabled and would therefore not be evaluated. | | `cache_variable.created_at` | string (date-time) | | (External Data) The date/time the object was created. Read-only. | | `cache_variable.created_by` | object | | (External Data) Reference to the user that created the object. Read-only. | | `cache_variable.created_by.id` | string | | Read-only. | | `cache_variable.created_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.updated_at` | string (date-time) | | (External Data) The date/time the object was last updated. Read-only. | | `cache_variable.updated_by` | object | | (External Data) Reference to the user that last updated the object. Read-only. | | `cache_variable.updated_by.id` | string | | Read-only. | | `cache_variable.updated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `cache_variable.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `cache_variable.configuration` | object | yes | (External Data) | | `cache_variable.configuration.type` | string | | The Cache Variable value will be set via a PUT API request to a dedicated endpoint that is made available after the creation of the cache variable. One of: `external_data`. | | `cache_variable.configuration.data_type` | string | | The type of data that will eventually be set for this cache variable via an API request. One of: `string`, `number`, `boolean`. | | `cache_variable.configuration.ttl_seconds` | integer | | The time to live (in seconds) for how long data sent to endpoint is persisted. After the TTL passes the data is deleted. | | `cache_variable.data_endpoint` | string (uri) | | (External Data) The endpoint that can be used to manage the data for an `external_data` type cache variable. Read-only. | Example: Response Example: Recent value cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "event.summary matches 'exception'" }, { "expression": "event.summary matches 'error'" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Trigger event count cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "trigger_event_count", "ttl_seconds": 2 }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` Example: Response Example: Disabled cache variable ```json { "cache_variable": [ { "id": "66bb56c3-2a17-44f3-9193-06b166d759ad", "name": "example_1", "conditions": [ { "expression": "not event.custom_details.errors exists" } ], "configuration": { "type": "recent_value", "source": "event.summary", "regex": ".*" }, "disabled": true, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-event-orchestration-feature-enablements # Update an Enablement for an Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/enablements/{feature_name}` Update the feature enablement setting for a specific product addon on an Event Orchestration. This setting controls enabling or disabling the set of features contained within the addon. Currently, only `aiops` is supported as a valid feature enablement. **Warning conditions**: - If the account is not entitled to use AIOps features, the setting will be updated, but a warning will be returned. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `feature_name` | string | yes | The feature enablement identifier, typically the name of the product addon. Currently only `aiops` is supported. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. One of: `aiops`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The feature enablement setting to apply. | Field | Type | Required | Description | |---|---|---|---| | `enablement` | object | yes | | | `enablement.feature` | string | | The name of the product addon whose set of features will be enabled or disabled. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Read-only. | | `enablement.enabled` | boolean | yes | A boolean value indicating whether the specified product addon is enabled or disabled. | | `enablement.updated_at` | string (date-time) | | The time the feature enablement was last updated. Read-only. | | `enablement.warnings` | array of object | | An array of warnings related to this feature enablement. Only present if warning conditions are met. Read-only. | | `enablement.warnings[].message` | string | | The warning message. | Example: Enable AIOps ```json { "enablement": { "enabled": true } } ``` Example: Disable AIOps ```json { "enablement": { "enabled": false } } ``` ## Response 200 The feature enablement setting was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `enablement` | object | | Same fields as `enablement` above. | Example: Success Response ```json { "enablement": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z" } ] } ``` Example: Response with No Entitlement Warning ```json { "enablement": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z", "warnings": [ { "message": "You can't use AIOps functionality with this Orchestration because your account hasn't purchased AIOps" } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-external-data-cache-var-data-on-global-orch # Update Data for an External Data Cache Variable on a Global Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/cache_variables/{cache_variable_id}/data` Update data for an `external_data` type Cache Variable on a Global Event Orchestration Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The updated data for an `external_data` type Cache Variable for this Event Orchestration. | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Request Example: Updated string ```json { "cache_variable_data": "Updated - Hello World!" } ``` Example: Request Example: Updated number ```json { "cache_variable_data": 85.1 } ``` Example: Request Example: Updated boolean ```json { "cache_variable_data": false } ``` ## Response 200 The data on an `external_data` type Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Response Example: String ```json { "cache_variable_data": "Updated - Hello World!", "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Number ```json { "cache_variable_data": 85.1, "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Boolean ```json { "cache_variable_data": false, "updated_at": "2021-11-18T16:42:01Z" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-external-data-cache-var-data-on-service-orch # Update Data for an External Data Cache Variable on a Service Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/services/{service_id}/cache_variables/{cache_variable_id}/data` Update the data for an `external_data` type Cache Variable on a Service Event Orchestration. Use External Data type Cache Variables to store string, number, or boolean values via a dedicated API endpoint. These stored values can then be used in conditions or actions in Event Orchestration rules. For more information see the [Knowledge Base](https://support.pagerduty.com/main/docs/event-orchestration-cache-variables) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `cache_variable_id` | string | yes | The ID of a Cache Variable. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The updated data for an `external_data` type Cache Variable for this Event Orchestration. | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Request Example: Updated string ```json { "cache_variable_data": "Updated - Hello World!" } ``` Example: Request Example: Updated number ```json { "cache_variable_data": 85.1 } ``` Example: Request Example: Updated boolean ```json { "cache_variable_data": false } ``` ## Response 200 The data on an `external_data` type Cache Variable for this Event Orchestration. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `cache_variable_data` | string | yes | (String Data) The string value to set on an external data cache variable configured with `data_type: string`. | | `updated_at` | string (date-time) | | (String Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | number | yes | (Number Data) The number value to set on an external data cache variable configured with `data_type: number`. | | `updated_at` | string (date-time) | | (Number Data) The date/time the cache variable data was last updated. Read-only. | | `cache_variable_data` | boolean | yes | (Boolean Data) The boolean value to set on an external data cache variable configured with `data_type: boolean`. | | `updated_at` | string (date-time) | | (Boolean Data) The date/time the cache variable data was last updated. Read-only. | Example: Response Example: String ```json { "cache_variable_data": "Updated - Hello World!", "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Number ```json { "cache_variable_data": 85.1, "updated_at": "2021-11-18T16:42:01Z" } ``` Example: Response Example: Boolean ```json { "cache_variable_data": false, "updated_at": "2021-11-18T16:42:01Z" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-active-status # Update the Service Orchestration active status for a Service `PUT https://api.pagerduty.com/event_orchestrations/services/{service_id}/active` Update a Service Orchestration's active status. A Service Orchestration allows you to set an active status based on whether an event will be evaluated against a service orchestration path (true) or service ruleset (false). For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Update Service Orchestration's active status. | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | The status of the service orchestration. | Example: Example Request ```json { "active": false } ``` ## Response 200 An object with the active status. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | The status of the service orchestration. | Example: Example Response ```json { "active": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-path-global # Update the Global Orchestration for an Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/global` Update the Global Orchestration for an Event Orchestration. Global Orchestration Rules allows you to create a set of Event Rules. These rules evaluate against all Events sent to an Event Orchestration. When a matching rule is found, it can modify and enhance the event and can route the event to another set of Global Rules within this Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Update Global Orchestration rules. Omitted rules and rule details are deleted. | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a set of "global" rules. Default: `global`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration these Global Rules belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | You must define at least a "start" set, but you can also define any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.drop_event` | boolean | | If true, this event will be dropped. Dropped events will not trigger or resolve an alert or an incident. Dropped events will not be evaluated against router rules. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | Example: Example Request ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to all events", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ], "route_to": "step-two" } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "Drop all events from the very-noisy monitoring tool", "id": "1f6d9a33", "conditions": [ { "expression": "event.source matches part 'very-noisy'" } ], "actions": { "drop_event": true } }, { "label": "Assign all database related incidents to the Database Team's escalation policy", "id": "4314d9ce", "conditions": [ { "expression": "event.source matches 'prod-db'" } ], "actions": { "escalation_policy": "PEYSGVF" } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true }, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } } } ``` ## Response 200 The Global Orchestration Rules object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a set of "global" rules. Default: `global`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration these Global Rules belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | You must define at least a "start" set, but you can also define any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.drop_event` | boolean | | If true, this event will be dropped. Dropped events will not trigger or resolve an alert or an incident. Dropped events will not be evaluated against router rules. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `warnings` | array of one of: object \| object | | | | `warnings[].message` | string | | (option 1) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 1) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 1) The feature that the current account plan does not have access to. Example values include: * `threshold_condition` * `nested_rules` * `suspend` * `automation_actions` * `cache_variable:automation_actions` * `cache_variable:annotate` * `variables` * `interpolation:annotate` * `interpolation:extractions` * `interpolation:incident_custom_field_updates` * `suppress` * `incident_custom_field_updates` * `dynamic_route_to` * `escalation_policy` * `aiops_routing_mismatch` | | `warnings[].feature_type` | string | | (option 1) Specifies whether the feature is a part of the rule's conditions, or its actions. Example values include: * `conditions` * `actions` * `nested_rules` * `global_orchestrations` * `aiops_routing` For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops_routing_mismatch`, `aiops_routing`) are unchanged. | | `warnings[].warning_type` | string | | (option 1) The type of warning that is being returned for the rule. One of: `forbidden_feature`, `invalid_routing`. | | `warnings[].message` | string | | (option 2) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 2) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 2) The feature that includes invalid data. Example values include: * `incident_custom_field_updates` * `escalation_policy` * `cache_variable:annotate` * `cache_variable:conditions` * `cache_variable:automation_actions` | | `warnings[].feature_type` | string | | (option 2) Specifies the feature type of the impacted item. Example values include: * `actions` * `conditions` | | `warnings[].warning_type` | string | | (option 2) The type of warning that is being returned for the rule. One of: `invalid_data`. | Example: Example Response ```json { "orchestration_path": { "type": "global", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/global", "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to all events", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ], "route_to": "step-two" } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "Drop all events from the very-noisy monitoring tool", "id": "1f6d9a33", "conditions": [ { "expression": "event.source matches part 'very-noisy'" } ], "actions": { "drop_event": true } }, { "label": "Assign all database related incidents to the Database Team's escalation policy", "id": "4314d9ce", "conditions": [ { "expression": "event.source matches 'prod-db'" } ], "actions": { "escalation_policy": "PEYSGVF" } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "rn1Mja13T1HBdmPChqFilSQXUW2fWXM_" }, "warnings": [ { "feature": "nested_rules", "feature_type": "nested_rules", "message": "This orchestration contains Nested Rules, which is not available on your account plan. The orchestration will be updated, however, only rules in the 'start' set will be evaluated", "rule_id": null, "warning_type": "forbidden_feature" }, { "feature": "variables", "feature_type": "actions", "message": "This rule uses Dynamic Field Enrichment & Extraction, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "extractions", "feature_type": "actions", "message": "This rule uses Dynamic Field Enrichment & Extraction, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "recurring_condition", "feature_type": "conditions", "message": "This rule uses Recurring Condition, which is a condition not available on your account plan. The rule will be updated, but it will not be evaluated by events", "rule_id": "cd770384", "warning_type": "forbidden_feature" }, { "feature": "incident_custom_field_updates", "feature_type": "actions", "message": "This rule uses Incident Custom Field update, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-path-router # Update the Router for an Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/router` Update a Global Orchestration's Routing Rules. An Orchestration Router allows you to create a set of Event Rules. The Router evaluates Events you send to this Global Orchestration against each of its rules, one at a time, and routes the event to a specific Service based on the first rule that matches. If an event doesn't match any rules, it'll be sent to service specified in as the `catch_all` or the "Unrouted" Orchestration if no service is specified. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Updates to Orchestration Router details. Omitted rules and rule details are deleted. | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "router" type set of rules. Default: `router`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Router belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | The Router contains a single set of rules (the "start" set). The Router evaluates Events against these Rules, one at a time, and routes each Event to a specific Service based on the first rule that matches. Min items: 1. Max items: 1. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.route_to` | string | | With a value of 'unrouted', all events are sent to the Unrouted Orchestration. Default: `unrouted`. | Example: Example Request ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Dynamically route events", "id": "763110d0", "actions": { "dynamic_route_to": { "source": "event.custom_details.pd_service", "regex": ".*", "lookup_by": "service_name" } } }, { "label": "Events relating to our relational database", "id": "1c26698b", "conditions": [ { "expression": "event.summary matches part 'database'" }, { "expression": "event.source matches regex 'db[0-9]+-server'" } ], "actions": { "route_to": "PB31XBA" } }, { "label": "Events relating to our www app server", "id": "d9801904", "conditions": [ { "expression": "event.summary matches part 'www'" } ], "actions": { "route_to": "PC2D9ML" } }, { "label": "Events relating to our delivery pipeline", "id": "ed624931", "conditions": [ { "expression": "trigger_count over 1 minute > 3" } ], "actions": { "route_to": "PQSJBMA" } } ] } ] } } ``` ## Response 200 The Orchestration Router object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "router" type set of rules. Default: `router`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Router belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | The Router contains a single set of rules (the "start" set). The Router evaluates Events against these Rules, one at a time, and routes each Event to a specific Service based on the first rule that matches. Min items: 1. Max items: 1. | | `orchestration_path.catch_all` | object | | When none of the rules match an event, the event will be routed according to the catch_all settings. | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.route_to` | string | | With a value of 'unrouted', all events are sent to the Unrouted Orchestration. Default: `unrouted`. | | `warnings` | array of one of: object | | List of applicable warnings messages for each rule using a feature not available on your account plan. | | `warnings[].message` | string | | (option 1) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 1) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 1) The feature that the current account plan does not have access to. Example values include: * `threshold_condition` * `nested_rules` * `suspend` * `automation_actions` * `cache_variable:automation_actions` * `cache_variable:annotate` * `variables` * `interpolation:annotate` * `interpolation:extractions` * `interpolation:incident_custom_field_updates` * `suppress` * `incident_custom_field_updates` * `dynamic_route_to` * `escalation_policy` * `aiops_routing_mismatch` | | `warnings[].feature_type` | string | | (option 1) Specifies whether the feature is a part of the rule's conditions, or its actions. Example values include: * `conditions` * `actions` * `nested_rules` * `global_orchestrations` * `aiops_routing` For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops_routing_mismatch`, `aiops_routing`) are unchanged. | | `warnings[].warning_type` | string | | (option 1) The type of warning that is being returned for the rule. One of: `forbidden_feature`, `invalid_routing`. | Example: Example Response ```json { "orchestration_path": { "type": "router", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/router", "sets": [ { "id": "start", "rules": [ { "label": "Dynamically route events", "id": "763110d0", "actions": { "dynamic_route_to": { "source": "event.custom_details.pd_service", "regex": ".*", "lookup_by": "service_name" } } }, { "label": "Events relating to our relational database", "id": "1c26698b", "conditions": [ { "expression": "event.summary matches part 'database'" }, { "expression": "event.source matches regex 'db[0-9]+-server'" } ], "actions": { "route_to": "PB31XBA" } }, { "label": "Events relating to our www app server", "id": "d9801904", "conditions": [ { "expression": "event.summary matches part 'www'" } ], "actions": { "route_to": "PC2D9ML" } }, { "label": "Events relating to our delivery pipeline", "id": "ed624931", "conditions": [ { "expression": "trigger_count over 1 minute > 3" } ], "actions": { "route_to": "PQSJBMA" } } ] } ], "catch_all": { "actions": { "route_to": "unrouted" } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "9co0z4b152oICsoV91_PW2.ww8ip_xap" }, "warnings": [ { "feature": "dynamic_route_to,", "feature_type": "actions,", "message": "This rule uses Dynamic Routing, which is an action not available on your account plan. The rule will be updated, but it will not be evaluated by events,", "rule_id": "763110d0,", "warning_type": "forbidden_feature" }, { "feature": "threshold_condition", "feature_type": "conditions", "message": "This rule uses Threshold Condition, which is a condition not available on your account plan. The rule will be updated, but it will not be evaluated by events", "rule_id": "ed624931", "warning_type": "forbidden_feature" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-path-service # Update the Service Orchestration for a Service `PUT https://api.pagerduty.com/event_orchestrations/services/{service_id}` Update a Service Orchestration. A Service Orchestration allows you to create a set of Event Rules. The Service Orchestration evaluates Events sent to this Service against each of its rules, beginning with the rules in the "start" set. When a matching rule is found, it can modify and enhance the event and can route the event to another set of rules within this Service Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Update Service Orchestration rules. Omitted rules and rule details are deleted. | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.migrated_at` | string (date-time) | | The date/time the service's Event Rules were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by` | object | | Reference to the user that converted the service's Event Rules to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by.id` | string | | Read-only. | | `orchestration_path.migrated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_from` | object | | Reference to the Service Event Rules that were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_from.id` | string | | Read-only. | | `orchestration_path.migrated_from.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_from.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_status` | string | | The status indicating whether the service's Event Rules were successfully converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `completed`. | | `orchestration_path.migrated_via` | string | | Indicates whether the conversion was performed via the PagerDuty API or PagerDuty website. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `API`, `UI`. | | `orchestration_path.type` | | | Indicates that these are sets of rules belonging to a service. Default: `service`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | The ID of the Service this Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `service_reference`. | | `orchestration_path.sets` | | | A Service Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions` | array of object | | Configure an Automation Action to be run for certain alert states. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].action_id` | string | | Automation Action ID. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].trigger_types` | array of string | | The Automation Action will be triggered whenever an alert reaches the specified state. Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | Example: Example Request ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to all events", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "pagerduty_automation_actions": [ { "action_id": "01CSB5SMOKCKVRI5GN0LJG7SMB", "trigger_types": [ "alert_triggered" ] } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ], "route_to": "step-two" } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "annotate": "Please use our P1 runbook: https://docs.test/p1-runbook", "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "If there's something wrong on the canary let the team know about it in our deployments Slack channel", "id": "1f6d9a33", "conditions": [ { "expression": "event.custom_details.hostname matches part 'canary'" } ], "actions": { "automation_actions": [ { "name": "Canary Slack Notification", "url": "https://our-slack-listerner.test/send-notification", "auto_send": true, "headers": [ { "key": "X-Notification-Source", "value": "PagerDuty Incident Webhook" } ], "parameters": [ { "key": "channel", "value": "#my-team-channel" }, { "key": "message", "value": "Something is wrong with the canary deployment" } ], "trigger_types": [ "alert_triggered" ] } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" } ] } }, { "label": "Pause the alert and trigger a reboot action if flaky server receives an error", "id": "c0163dbe", "conditions": [ { "expression": "event.custom_details.hostname matches part 'staging'" } ], "actions": { "suspend": 300, "pagerduty_automation_actions": [ { "action_id": "01CSBCGJXMG7ABIJZKPD8P9RCL", "trigger_types": [ "alert_suspended" ] } ] } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true }, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } } } ``` ## Response 200 The Service Orchestration object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.migrated_at` | string (date-time) | | The date/time the service's Event Rules were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by` | object | | Reference to the user that converted the service's Event Rules to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_by.id` | string | | Read-only. | | `orchestration_path.migrated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_from` | object | | Reference to the Service Event Rules that were converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `orchestration_path.migrated_from.id` | string | | Read-only. | | `orchestration_path.migrated_from.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `orchestration_path.migrated_from.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration_path.migrated_status` | string | | The status indicating whether the service's Event Rules were successfully converted to this Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `completed`. | | `orchestration_path.migrated_via` | string | | Indicates whether the conversion was performed via the PagerDuty API or PagerDuty website. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `API`, `UI`. | | `orchestration_path.type` | | | Indicates that these are sets of rules belonging to a service. Default: `service`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | The ID of the Service this Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `service_reference`. | | `orchestration_path.sets` | | | A Service Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.suppress` | boolean | | If true, the resulting alert is suppressed. Suppressed alerts will not trigger an incident. | | `orchestration_path.catch_all.actions.suspend` | integer | | The number of seconds to suspend the resulting alert before triggering. This effectively pauses incident notifications. If a resolve event arrives before the alert triggers then PagerDuty won't create an incident for this the resulting alert. | | `orchestration_path.catch_all.actions.priority` | string | | The ID of the priority you want to set on resulting incident. You can find the list of priority IDs for your account by calling the priorities endpoint. | | `orchestration_path.catch_all.actions.escalation_policy` | string | | The ID of the Escalation Policy you want to assign incidents to. Event rules with this action will override the Escalation Policy already set on a Service's settings, with what is configured by this action. | | `orchestration_path.catch_all.actions.annotate` | string | | Add this text as a note on the resulting incident. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the note. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions` | array of object | | Configure an Automation Action to be run for certain alert states. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].action_id` | string | | Automation Action ID. | | `orchestration_path.catch_all.actions.pagerduty_automation_actions[].trigger_types` | array of string | | The Automation Action will be triggered whenever an alert reaches the specified state. Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions` | array of object | | Create a Webhoook associated with the resulting incident. | | `orchestration_path.catch_all.actions.automation_actions[].name` | string | | The name of the Webhook. | | `orchestration_path.catch_all.actions.automation_actions[].url` | string | | The API endpoint where PagerDuty's servers will send the webhook request. | | `orchestration_path.catch_all.actions.automation_actions[].auto_send` | boolean | | When true, PagerDuty's servers will automatically send this webhook request as soon as the resulting incident or alert is created. When false, your incident responder will be able to manually trigger the Webhook via the PagerDuty website & mobile app. Default: `false`. | | `orchestration_path.catch_all.actions.automation_actions[].headers` | array of object | | Specify custom key/value pairs that'll be sent with the webhook request as request headers. | | `orchestration_path.catch_all.actions.automation_actions[].headers[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].headers[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the header value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `orchestration_path.catch_all.actions.automation_actions[].trigger_types` | array of string | | The Webhook will be associated (or automatically triggered, if `auto_send` is `true`) with the incident, whenever an alert reaches the specified state Note: `auto_send` must be `true` for trigger types of `alert_suppressed` and `alert_suspended` Min items: 1. Max items: 1. Items must be unique. | | `orchestration_path.catch_all.actions.automation_actions[].parameters` | array of object | | Specify custom key/value pairs that'll be included in the webhook request's JSON payload. | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].key` | string | | | | `orchestration_path.catch_all.actions.automation_actions[].parameters[].value` | string | | AIOps users can additionally use the {{event}} variable to include elements of the event payload in the parameter value. | | `orchestration_path.catch_all.actions.incident_custom_field_updates` | array of object | | Configure custom field updates for the incident. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].id` | string | | Unique identifier for the custom field resource. You can find the list of IDs by calling the List Custom Fields endpoint. | | `orchestration_path.catch_all.actions.incident_custom_field_updates[].value` | string | | A value that will be used to populate the specified Incident Custom Field. AIOps users can additionally use the {{event}} variable to include elements of the event payload in the custom field value. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. | | `warnings` | array of one of: object \| object | | | | `warnings[].message` | string | | (option 1) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 1) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 1) The feature that the current account plan does not have access to. Example values include: * `threshold_condition` * `nested_rules` * `suspend` * `automation_actions` * `cache_variable:automation_actions` * `cache_variable:annotate` * `variables` * `interpolation:annotate` * `interpolation:extractions` * `interpolation:incident_custom_field_updates` * `suppress` * `incident_custom_field_updates` * `dynamic_route_to` * `escalation_policy` * `aiops_routing_mismatch` | | `warnings[].feature_type` | string | | (option 1) Specifies whether the feature is a part of the rule's conditions, or its actions. Example values include: * `conditions` * `actions` * `nested_rules` * `global_orchestrations` * `aiops_routing` For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops_routing_mismatch`, `aiops_routing`) are unchanged. | | `warnings[].warning_type` | string | | (option 1) The type of warning that is being returned for the rule. One of: `forbidden_feature`, `invalid_routing`. | | `warnings[].message` | string | | (option 2) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 2) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 2) The feature that includes invalid data. Example values include: * `incident_custom_field_updates` * `escalation_policy` * `cache_variable:annotate` * `cache_variable:conditions` * `cache_variable:automation_actions` | | `warnings[].feature_type` | string | | (option 2) Specifies the feature type of the impacted item. Example values include: * `actions` * `conditions` | | `warnings[].warning_type` | string | | (option 2) The type of warning that is being returned for the rule. One of: `invalid_data`. | Example: Example Response ```json { "orchestration_path": { "type": "service", "parent": { "id": "PC2D9ML", "self": "https://api.pagerduty.com/service/PC2D9ML", "type": "service_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/service/PC2D9ML", "sets": [ { "id": "start", "rules": [ { "label": "Always apply some consistent event transformations to all events", "id": "c91f72f3", "conditions": [], "actions": { "variables": [ { "name": "hostname", "path": "event.component", "value": "hostname: (.*)", "type": "regex" } ], "extractions": [ { "template": "{{variables.hostname}}", "target": "event.custom_details.hostname" }, { "source": "event.source", "regex": "www (.*) service", "target": "event.source" } ], "pagerduty_automation_actions": [ { "action_id": "01CSB5SMOKCKVRI5GN0LJG7SMB", "trigger_types": [ "alert_triggered" ] } ], "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#my-team-channel" }, { "id": "PN1C4A2", "value": "{{event.timestamp}}" } ], "route_to": "step-two" } } ] }, { "id": "step-two", "rules": [ { "label": "All critical alerts should be treated as P1 incidents", "id": "7c54529d", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "annotate": "Please use our P1 runbook: https://docs.test/p1-runbook", "priority": "P0IN2KQ", "suppress": false, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#p1-incident-response" } ] } }, { "label": "If there's something wrong on the canary let the team know about it in our deployments Slack channel", "id": "1f6d9a33", "conditions": [ { "expression": "event.custom_details.hostname matches part 'canary'" } ], "actions": { "automation_actions": [ { "name": "Canary Slack Notification", "url": "https://our-slack-listerner.test/send-notification", "auto_send": true, "headers": [ { "key": "X-Notification-Source", "value": "PagerDuty Incident Webhook" } ], "parameters": [ { "key": "channel", "value": "#my-team-channel" }, { "key": "message", "value": "Something is wrong with the canary deployment" } ], "trigger_types": [ "alert_triggered" ] } ] } }, { "label": "Pause the alert and trigger a reboot action if flaky server receives an error", "id": "c0163dbe", "conditions": [ { "expression": "event.custom_details.hostname matches part 'staging'" } ], "actions": { "suspend": 300, "pagerduty_automation_actions": [ { "action_id": "01CSBCGJXMG7ABIJZKPD8P9RCL", "trigger_types": [ "alert_suspended" ] } ] } }, { "label": "Never bother the on-call for info-level events outside of work hours", "id": "cd770384", "conditions": [ { "expression": "event.severity matches 'info' and not (now in Mon,Tue,Wed,Thu,Fri 09:00:00 to 17:00:00 America/Los_Angeles)" } ], "actions": { "suppress": true } } ] } ], "catch_all": { "actions": { "suppress": true, "incident_custom_field_updates": [ { "id": "PEXCK89", "value": "#general-incident-notifications" } ] } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "rn1Mja13T1HBdmPChqFilSQXUW2fWXM_" }, "warnings": [ { "feature": "nested_rules", "feature_type": "nested_rules", "message": "This orchestration contains Nested Rules, which is not available on your account plan. The orchestration will be updated, however, only rules in the 'start' set will be evaluated", "rule_id": null, "warning_type": "forbidden_feature" }, { "feature": "variables", "feature_type": "actions", "message": "This rule uses Dynamic Field Enrichment & Extraction, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "extractions", "feature_type": "actions", "message": "This rule uses Dynamic Field Enrichment & Extraction, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "pagerduty_automation_actions", "feature_type": "actions", "message": "This rule uses PagerDuty Automation Actions, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "automation_actions", "feature_type": "actions", "message": "This rule uses Automation Actions, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "1f6d9a33", "warning_type": "forbidden_feature" }, { "feature": "recurring_condition", "feature_type": "conditions", "message": "This rule uses Recurring Condition, which is a condition not available on your account plan. The rule will be updated, but it will not be evaluated by events", "rule_id": "c91f72f3", "warning_type": "forbidden_feature" }, { "feature": "incident_custom_field_updates", "feature_type": "actions", "message": "This rule uses Incident Custom Field update, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "4g6d2a901", "warning_type": "forbidden_feature" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-path-unrouted # Update the Unrouted Orchestration for an Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/unrouted` Update a Global Event Orchestration's Rules for Unrouted events. An Unrouted Orchestration allows you to create a set of Event Rules that will be evaluated against all events that don't match any rules in the Global Orchestration's Router. Events that reach the Unrouted Orchestration will never be routed to a specific Service. The Unrouted Orchestration evaluates Events sent to it against each of its rules, beginning with the rules in the "start" set. When a matching rule is found, it can modify and enhance the event and can route the event to another set of rules within this Unrouted Orchestration for further processing. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) Updates to Unrouted Orchestration rules. Omitted rules and rule details are deleted. | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "unrouted" type set of rules. Default: `unrouted`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Unrouted Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | An Unrouted Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | Example: Example Request ```json { "orchestration_path": { "sets": [ { "id": "start", "rules": [ { "label": "Update the summary of un-matched Critical alerts so they're easier to spot", "id": "38880ffb", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "extractions": [ { "target": "event.summary", "template": "[Critical Unrouted] {{event.summary}}" } ] } }, { "label": "Reduce the severity of all other unrouted events", "id": "3896801e", "conditions": [], "actions": { "severity": "info" } } ] } ], "catch_all": { "actions": { "suppress": true } } } } ``` ## Response 200 The Unrouted Orchestration object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration_path` | object | yes | | | `orchestration_path.type` | | | Indicates that these are a "unrouted" type set of rules. Default: `unrouted`. | | `orchestration_path.parent` | object | | | | `orchestration_path.parent.id` | | | ID of the Global Event Orchestration this Unrouted Orchestration belongs to. | | `orchestration_path.parent.type` | | | One of: `event_orchestration_reference`. | | `orchestration_path.sets` | | | An Unrouted Orchestration must contain at least a "start" set, but can contain any number of additional sets that are routed to by other rules to form a directional graph. | | `orchestration_path.catch_all` | object | | | | `orchestration_path.catch_all.actions` | object | | | | `orchestration_path.catch_all.actions.severity` | string | | Set the severity of the resulting alert. One of: `info`, `error`, `warning`, `critical`. | | `orchestration_path.catch_all.actions.event_action` | string | | Set whether the resulting alert status is trigger or resolve. One of: `trigger`, `resolve`. | | `orchestration_path.catch_all.actions.variables` | array of object | | Populate variables from event payloads and use those variables in other event actions. | | `orchestration_path.catch_all.actions.variables[].name` | string | | The name of the variable. | | `orchestration_path.catch_all.actions.variables[].path` | string | | Path to a field in an event, in dot-notation. | | `orchestration_path.catch_all.actions.variables[].type` | string | | The type of operation to populate the variable. Currently only Regex-based variable extraction is supported. One of: `regex`. | | `orchestration_path.catch_all.actions.variables[].value` | string | | A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 1) The PD-CEF field that will be set with the value from the template. | | `orchestration_path.catch_all.actions.extractions[].template` | string | | (option 1) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `orchestration_path.catch_all.actions.extractions[].target` | string | | (option 2) The PD-CEF field that will be set with the value from the regex. | | `orchestration_path.catch_all.actions.extractions[].regex` | string | | (option 2) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `orchestration_path.catch_all.actions.extractions[].source` | string | | (option 2) The path to the event field where the regex will be applied to extract a value. | | `warnings` | array of one of: object | | List of applicable warnings messages for each rule using a feature not available on your account plan. | | `warnings[].message` | string | | (option 1) A description of the warning and any potential side effects. | | `warnings[].rule_id` | string | | (option 1) The ID of the rule using the feature. | | `warnings[].feature` | string | | (option 1) The feature that the current account plan does not have access to. Example values include: * `threshold_condition` * `nested_rules` * `suspend` * `automation_actions` * `cache_variable:automation_actions` * `cache_variable:annotate` * `variables` * `interpolation:annotate` * `interpolation:extractions` * `interpolation:incident_custom_field_updates` * `suppress` * `incident_custom_field_updates` * `dynamic_route_to` * `escalation_policy` * `aiops_routing_mismatch` | | `warnings[].feature_type` | string | | (option 1) Specifies whether the feature is a part of the rule's conditions, or its actions. Example values include: * `conditions` * `actions` * `nested_rules` * `global_orchestrations` * `aiops_routing` For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops_routing_mismatch`, `aiops_routing`) are unchanged. | | `warnings[].warning_type` | string | | (option 1) The type of warning that is being returned for the rule. One of: `forbidden_feature`, `invalid_routing`. | Example: Example Response ```json { "orchestration_path": { "type": "unrouted", "parent": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "type": "event_orchestration_reference" }, "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694/router", "sets": [ { "id": "start", "rules": [ { "label": "Update the summary of un-matched Critical alerts so they're easier to spot", "id": "38880ffb", "conditions": [ { "expression": "event.severity matches 'critical'" } ], "actions": { "extractions": [ { "target": "event.summary", "template": "[Critical Unrouted] {{event.summary}}" } ] } }, { "label": "Reduce the severity of all other unrouted events", "id": "3896801e", "conditions": [], "actions": { "severity": "info" } } ] } ], "catch_all": { "actions": { "suppress": true } }, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-18T16:42:01Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "aZO.EEf9zWb9Vg0NYq.Uqad1hOC2Maod" }, "warnings": [ { "feature": "extractions", "feature_type": "actions", "message": "This rule uses Dynamic Field Enrichment & Extraction, which is an action not available on your account plan. The rule will be updated, but the action will not be fired when the rule is evaluated", "rule_id": "3896801e", "warning_type": "forbidden_feature" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orchestration # Update an Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}` Update a Global Event Orchestration. Global Event Orchestrations allow you define a set of Global Rules and Router Rules, so that when you ingest events using the Orchestration's Routing Key your events will have actions applied via the Global Rules & then routed to the correct Service by the Router Rules, based on the event's content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `orchestration` | object | yes | | | `orchestration.id` | string | | ID of the Orchestration. Read-only. | | `orchestration.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.name` | string | | Name of the Orchestration. | | `orchestration.description` | string | | A description of this Orchestration's purpose. | | `orchestration.team` | object | | Reference to the team that owns the Orchestration. If none is specified, only admins have access. | | `orchestration.team.id` | string | | | | `orchestration.team.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.integrations` | array of object | | Read-only. | | `orchestration.integrations[].id` | string | | ID of the Integration. Read-only. | | `orchestration.integrations[].label` | string | | Name of the Integration. | | `orchestration.integrations[].parameters` | object | | Read-only. | | `orchestration.integrations[].parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `orchestration.integrations[].parameters.type` | string | | Read-only. Default: `global`. | | `orchestration.routes` | integer | | Number of different Service Orchestration being routed to. Read-only. | | `orchestration.created_at` | string (date-time) | | The date the Orchestration was created at. Read-only. | | `orchestration.created_by` | object | | Reference to the user that has created the Orchestration. Read-only. | | `orchestration.created_by.id` | string | | Read-only. | | `orchestration.created_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.created_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.updated_at` | string (date-time) | | The date the Orchestration was last updated. Read-only. | | `orchestration.updated_by` | object | | Reference to the user that has updated the Orchestration last. Read-only. | | `orchestration.updated_by.id` | string | | Read-only. | | `orchestration.updated_by.type` | string | | A string that determines the schema of the object. Read-only. | | `orchestration.updated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `orchestration.version` | string | | Version of the Orchestration. Read-only. | Example: Example: Change name ```json { "orchestration": { "name": "Go-Kart Orchestration" } } ``` Example: Example: Change team ```json { "orchestration": { "team": { "id": "PWL7QXS" } } } ``` Example: Example: Change description ```json { "orchestration": { "description": "Orchestration that does some stuff" } } ``` ## Response 200 The Orchestration that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `orchestration` | object | | Same fields as `orchestration` above. | Example: Response Example ```json { "orchestration": { "id": "b02e973d-9620-4e0a-9edc-00fedf7d4694", "self": "https://api.pagerduty.com/event_orchestrations/b02e973d-9620-4e0a-9edc-00fedf7d4694", "name": "Go-Kart Orchestration", "description": "Orchestration that does some stuff", "team": { "id": "PWL7QXS", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PWL7QXS" }, "integrations": [ { "id": "9c5ff030-12da-4204-a067-25ee61a8df6c", "label": "Go-Kart Orchestration Default Integration", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } ], "routes": 0, "created_at": "2021-11-18T16:42:01Z", "created_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "updated_at": "2021-11-19T11:42:32Z", "updated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "version": "BrWLKQBLm8QO2ZYQ0GosHLxdbgWZ0ZR3" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orchestration-integration # Update an Integration for an Event Orchestration `PUT https://api.pagerduty.com/event_orchestrations/{id}/integrations/{integration_id}` Update an Integration associated with this Event Orchestrations. You can use the Routing Key from this Integration to send events to PagerDuty! For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#event-orchestrations) Scoped OAuth requires: `event_orchestrations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of an Event Orchestration. | | `integration_id` | string | yes | The ID of an Integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | | | `integration.label` | string | yes | Name of the Integration. | Example: Example: Update an Integration ```json { "integration": { "label": "New Name for my Integration" } } ``` ## Response 200 The Integration that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | | | | `integration.id` | string | | ID of the Integration. Read-only. | | `integration.label` | string | | Name of the Integration. | | `integration.parameters` | object | | Read-only. | | `integration.parameters.routing_key` | string | | Routing Key used to send Events to this Orchestration. Read-only. | | `integration.parameters.type` | string | | Read-only. Default: `global`. | Example: Response Example ```json { "integration": { "id": "11832872-88b6-4661-8972-db5712b69496", "label": "New Name for my Integration", "parameters": { "routing_key": "R028DIE06SNKNO6V5ACSLRV7Y0TUVG7T", "type": "global" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extension-schemas/get-extension-schema # Get an extension vendor `GET https://api.pagerduty.com/extension_schemas/{id}` Get details about one specific extension vendor. A PagerDuty extension vendor represents a specific type of outbound extension such as Generic Webhook, Slack, ServiceNow. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extension-schemas) Scoped OAuth requires: `extension_schemas.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The extension vendor requested ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `extension_schema` | object | yes | | | `extension_schema.icon_url` | string (url) | | A small logo, 18-by-18 pixels. Read-only. | | `extension_schema.logo_url` | string (url) | | A large logo, 75 pixels high and no more than 300 pixels wide. Read-only. | | `extension_schema.label` | string | | Human friendly display label. Read-only. | | `extension_schema.key` | string | | Machine friendly display label. Read-only. | | `extension_schema.description` | string | | The long description for the Extension. | | `extension_schema.guide_url` | string (url) | | A link to the extension's support guide. Read-only. | | `extension_schema.send_types` | array of string | | The types of PagerDuty incident events that will activate this Extension. Items must be unique. | | `extension_schema.url` | string | | The url that the webhook payload will be sent to for this Extension. Read-only. | Example: Response Example ```json { "extension_schema": { "id": "PJFWPEP", "type": "extension_schema", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP", "description": "Long description here", "guide_url": "https://developer.pagerduty.com", "icon_url": "https://extension.com/extension.png", "key": "generic_webhook", "label": "Generic Webhook", "logo_url": "https://extension.com/logo.png", "send_types": [ "trigger", "acknowledge", "resolve", "delegate", "escalate", "unacknowledge", "assign" ], "url": "" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extension-schemas/list-extension-schemas # List extension schemas `GET https://api.pagerduty.com/extension_schemas` List all extension schemas. A PagerDuty extension vendor represents a specific type of outbound extension such as Generic Webhook, Slack, ServiceNow. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extension-schemas) Scoped OAuth requires: `extension_schemas.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of extension schemas. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `extension_schemas` | array of object | yes | | | `extension_schemas[].icon_url` | string (url) | | A small logo, 18-by-18 pixels. Read-only. | | `extension_schemas[].logo_url` | string (url) | | A large logo, 75 pixels high and no more than 300 pixels wide. Read-only. | | `extension_schemas[].label` | string | | Human friendly display label. Read-only. | | `extension_schemas[].key` | string | | Machine friendly display label. Read-only. | | `extension_schemas[].description` | string | | The long description for the Extension. | | `extension_schemas[].guide_url` | string (url) | | A link to the extension's support guide. Read-only. | | `extension_schemas[].send_types` | array of string | | The types of PagerDuty incident events that will activate this Extension. Items must be unique. | | `extension_schemas[].url` | string | | The url that the webhook payload will be sent to for this Extension. Read-only. | Example: Response Example ```json { "extension_schemas": [ { "id": "PJFWPEP", "type": "extension_schema", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP", "description": "Long description here", "guide_url": "https://developer.pagerduty.com", "icon_url": "https://extension.com/extension.png", "key": "generic_webhook", "label": "Generic Webhook", "logo_url": "https://extension.com/logo.png", "send_types": [ "trigger", "acknowledge", "resolve", "delegate", "escalate", "unacknowledge", "assign" ], "url": "" } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/create-extension # Create an extension `POST https://api.pagerduty.com/extensions` Create a new Extension. Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The extension to be created | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | | | `extension.id` | string | | Read-only. | | `extension.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.type` | string | | The type of object being created. One of: `extension`. Default: `extension`. | | `extension.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.name` | string | yes | The name of the extension. | | `extension.endpoint_url` | string (url) | | The url of the extension. | | `extension.extension_objects` | array of object | yes | The objects for which the extension applies. | | `extension.extension_objects[].id` | string | yes | Read-only. | | `extension.extension_objects[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_objects[].type` | string | yes | One of: `service_reference`. | | `extension.extension_objects[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_objects[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.extension_schema` | object | yes | | | `extension.extension_schema.id` | string | yes | Read-only. | | `extension.extension_schema.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_schema.type` | string | yes | One of: `extension_schema_reference`. | | `extension.extension_schema.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_schema.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.temporarily_disabled` | boolean | | Whether or not this extension is temporarily disabled; for example, a webhook extension that is repeatedly rejected by the server. Read-only. Default: `false`. | | `extension.config` | object | | The object that contains extension configuration values depending on the extension schema specification. | Example: Request Example ```json { "extension": { "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference" } ] } } ``` Example: Request Example with Custom Headers ```json { "extension": { "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference" } ], "config": { "headers": [ { "name": "Authorization", "value": "Token token=super_secret_token_value" } ] } } } ``` ## Response 201 The extension that was created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | Same fields as `extension` above. | Example: Response Example ```json { "extension": { "id": "PPGPXHO", "self": "https://api.pagerduty.com/extensions/PPGPXHO", "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "summary": "My Webhook", "type": "extension", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Callbacks - `webhookV2` - `webhookV1` ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/delete-extension # Delete an extension `DELETE https://api.pagerduty.com/extensions/{id}` Delete an existing extension. Once the extension is deleted, it will not be accessible from the web UI and new incidents won't be able to be created for this extension. Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The extension was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/enable-extension # Enable an extension `POST https://api.pagerduty.com/extensions/{id}/enable` Enable an extension that is temporarily disabled. (This API does not require a request body.) Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The extension that was successfully enabled. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | | | `extension.id` | string | | Read-only. | | `extension.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.type` | string | | The type of object being created. One of: `extension`. Default: `extension`. | | `extension.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.name` | string | yes | The name of the extension. | | `extension.endpoint_url` | string (url) | | The url of the extension. | | `extension.extension_objects` | array of object | yes | The objects for which the extension applies. | | `extension.extension_objects[].id` | string | yes | Read-only. | | `extension.extension_objects[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_objects[].type` | string | yes | One of: `service_reference`. | | `extension.extension_objects[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_objects[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.extension_schema` | object | yes | | | `extension.extension_schema.id` | string | yes | Read-only. | | `extension.extension_schema.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_schema.type` | string | yes | One of: `extension_schema_reference`. | | `extension.extension_schema.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_schema.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.temporarily_disabled` | boolean | | Whether or not this extension is temporarily disabled; for example, a webhook extension that is repeatedly rejected by the server. Read-only. Default: `false`. | | `extension.config` | object | | The object that contains extension configuration values depending on the extension schema specification. | Example: Response Example ```json { "extension": { "id": "PPGPXHO", "self": "https://api.pagerduty.com/extensions/PPGPXHO", "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "summary": "My Webhook", "type": "extension", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/get-extension # Get an extension `GET https://api.pagerduty.com/extensions/{id}` Get details about an existing extension. Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `extension_schemas`, `extension_objects`, `temporarily_disabled`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The extension that was requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | | | `extension.id` | string | | Read-only. | | `extension.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.type` | string | | The type of object being created. One of: `extension`. Default: `extension`. | | `extension.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.name` | string | yes | The name of the extension. | | `extension.endpoint_url` | string (url) | | The url of the extension. | | `extension.extension_objects` | array of object | yes | The objects for which the extension applies. | | `extension.extension_objects[].id` | string | yes | Read-only. | | `extension.extension_objects[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_objects[].type` | string | yes | One of: `service_reference`. | | `extension.extension_objects[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_objects[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.extension_schema` | object | yes | | | `extension.extension_schema.id` | string | yes | Read-only. | | `extension.extension_schema.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_schema.type` | string | yes | One of: `extension_schema_reference`. | | `extension.extension_schema.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_schema.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.temporarily_disabled` | boolean | | Whether or not this extension is temporarily disabled; for example, a webhook extension that is repeatedly rejected by the server. Read-only. Default: `false`. | | `extension.config` | object | | The object that contains extension configuration values depending on the extension schema specification. | Example: Response Example ```json { "extension": { "id": "PPGPXHO", "self": "https://api.pagerduty.com/extensions/PPGPXHO", "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "summary": "My Webhook", "type": "extension", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ], "temporarily_disabled": false } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/list-extensions # List extensions `GET https://api.pagerduty.com/extensions` List existing extensions. Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `extension_object_id` | string | | The id of the extension object you want to filter by. | | `extension_schema_id` | string | | Filter the extensions by extension vendor id. | | `include[]` | string | | Array of additional details to include. One of: `extension_objects`, `extension_schemas`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of extensions. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `extensions` | array of object | yes | | | `extensions[].id` | string | | Read-only. | | `extensions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extensions[].type` | string | | The type of object being created. One of: `extension`. Default: `extension`. | | `extensions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extensions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extensions[].name` | string | yes | The name of the extension. | | `extensions[].endpoint_url` | string (url) | | The url of the extension. | | `extensions[].extension_objects` | array of object | yes | The objects for which the extension applies. | | `extensions[].extension_objects[].id` | string | yes | Read-only. | | `extensions[].extension_objects[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extensions[].extension_objects[].type` | string | yes | One of: `service_reference`. | | `extensions[].extension_objects[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extensions[].extension_objects[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extensions[].extension_schema` | object | yes | | | `extensions[].extension_schema.id` | string | yes | Read-only. | | `extensions[].extension_schema.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extensions[].extension_schema.type` | string | yes | One of: `extension_schema_reference`. | | `extensions[].extension_schema.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extensions[].extension_schema.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extensions[].temporarily_disabled` | boolean | | Whether or not this extension is temporarily disabled; for example, a webhook extension that is repeatedly rejected by the server. Read-only. Default: `false`. | | `extensions[].config` | object | | The object that contains extension configuration values depending on the extension schema specification. | Example: Response Example ```json { "extensions": [ { "id": "PPGPXHO", "self": "https://api.pagerduty.com/extensions/PPGPXHO", "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "summary": "My Webhook", "type": "extension", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/extensions/update-extension # Update an extension `PUT https://api.pagerduty.com/extensions/{id}` Update an existing extension. Extensions are representations of Extension Schema objects that are attached to Services. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#extensions) Scoped OAuth requires: `extensions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The extension to be updated. | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | | | `extension.id` | string | | Read-only. | | `extension.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.type` | string | | The type of object being created. One of: `extension`. Default: `extension`. | | `extension.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.name` | string | yes | The name of the extension. | | `extension.endpoint_url` | string (url) | | The url of the extension. | | `extension.extension_objects` | array of object | yes | The objects for which the extension applies. | | `extension.extension_objects[].id` | string | yes | Read-only. | | `extension.extension_objects[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_objects[].type` | string | yes | One of: `service_reference`. | | `extension.extension_objects[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_objects[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.extension_schema` | object | yes | | | `extension.extension_schema.id` | string | yes | Read-only. | | `extension.extension_schema.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `extension.extension_schema.type` | string | yes | One of: `extension_schema_reference`. | | `extension.extension_schema.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `extension.extension_schema.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `extension.temporarily_disabled` | boolean | | Whether or not this extension is temporarily disabled; for example, a webhook extension that is repeatedly rejected by the server. Read-only. Default: `false`. | | `extension.config` | object | | The object that contains extension configuration values depending on the extension schema specification. | Example: Request Example ```json { "extension": { "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference" } ] } } ``` Example: Request Example with Custom Headers ```json { "extension": { "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference" } ], "config": { "headers": [ { "name": "Authorization", "value": "Token token=super_secret_token_value" } ] } } } ``` ## Response 200 The extension that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `extension` | object | yes | Same fields as `extension` above. | Example: Response Example ```json { "extension": { "id": "PPGPXHO", "self": "https://api.pagerduty.com/extensions/PPGPXHO", "endpoint_url": "https://example.com/receive_a_pagerduty_webhook", "name": "My Webhook", "summary": "My Webhook", "type": "extension", "extension_schema": { "id": "PJFWPEP", "type": "extension_schema_reference", "summary": "Generic Webhook", "self": "https://api.pagerduty.com/extension_schemas/PJFWPEP" }, "extension_objects": [ { "id": "PIJ90N7", "type": "service_reference", "summary": "My Application Service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7" } ] } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/create-custom-fields-field # Create a Field `POST https://api.pagerduty.com/incidents/custom_fields` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/create-incident-type-custom-field) Creates a new Custom Field on the Base Incident Type, along with the Field Options if provided. \ An account may have up to 10 Fields. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.field_options` | array \| null | | The fixed list of value options that may be stored in this field. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | Example: Example: With field_options and single-value ```json { "field": { "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "default_value": "production", "field_options": [ { "data": { "data_type": "string", "value": "production" } }, { "data": { "data_type": "string", "value": "staging" } } ] } } ``` Example: Example: With field_options and multi-value ```json { "field": { "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "multi_value_fixed", "default_value": [ "production", "staging" ], "field_options": [ { "data": { "data_type": "string", "value": "production" } }, { "data": { "data_type": "string", "value": "staging" } } ] } } ``` Example: Example: Without field_options ```json { "field": { "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "single_value", "default_value": "production" } } ``` ## Response 201 The field object created, along with the Field Options if provided. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Same fields as `field` above. | Example: Example: With field_options and single-value ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "environment", "display_name": "Environment", "field_type": "single_value_fixed", "description": "The environment that the issue occurred in", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z", "default_value": "staging", "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` Example: Example: With field_options and multi-value ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "environment", "display_name": "Environment", "field_type": "multi_value_fixed", "description": "The environment that the issue occurred in", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z", "default_value": [ "production", "staging" ], "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` Example: Example: Without field_options ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "field_type": "single_value", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "default_value": "production", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/create-custom-fields-field-option # Create a Field Option `POST https://api.pagerduty.com/incidents/custom_fields/{field_id}/field_options` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/create-incident-type-custom-field-field-options) Create a new Field Option for a Custom Field on the Base Incident Type. Field Options may only be created for Fields that have `field_options`. A Field may have no more than 10 enabled options. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | yes | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "production" } } } ``` ## Response 201 The field option created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | Same fields as `field_option` above. | Example: Response Example ```json { "field_option": { "id": "PQ9K7I8", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/delete-custom-fields-field # Delete a Field `DELETE https://api.pagerduty.com/incidents/custom_fields/{field_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/delete-incident-type-custom-field) Delete a Custom Field from the Base Incident Type. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Response 204 The field was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/delete-custom-fields-field-option # Delete a Field Option `DELETE https://api.pagerduty.com/incidents/custom_fields/{field_id}/field_options/{field_option_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options/{field_option_id}](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/delete-incident-type-custom-field-field-option) Delete a Field Option for a Custom Field on the Base Incident Type. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | | `field_option_id` | string | yes | The ID of the field option. | ## Response 204 The field option was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/get-custom-fields-field # Get a Field `GET https://api.pagerduty.com/incidents/custom_fields/{field_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/get-incident-type-custom-field) Show detailed information about a Custom Field on the Base Incident Type. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Response 200 The field requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.field_options` | array \| null | | The fixed list of value options that may be stored in this field. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | Example: Example: No query parameters ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "multi_value", "default_value": null, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` Example: Example: Using include[]=field_options ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z", "default_value": null, "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/list-custom-fields-field-options # List Field Options `GET https://api.pagerduty.com/incidents/custom_fields/{field_id}/field_options` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/list-incident-type-custom-field) List all enabled Field Options for a Custom Field on the Base Incident Type. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Response 200 A list of field options. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_options` | array of object | yes | | | `field_options[].data` | one of: object | yes | | | `field_options[].data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_options[].data.value` | string | yes | (option 1) Max length: 100. | | `field_options[].id` | string | yes | The ID of the resource. Read-only. | | `field_options[].type` | string | yes | Read-only. One of: `field_option`. | | `field_options[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_options[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_options": [ { "id": "PQ9K7I8", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } ``` ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/list-custom-fields-fields # List Fields `GET https://api.pagerduty.com/incidents/custom_fields` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/list-incident-type-custom-fields) List Custom Fields on the Base Incident Type. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Response 200 A list of fields. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `fields` | array of object | yes | | | `fields[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `fields[].data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `fields[].default_value` | one of: object \| object \| object \| object \| object \| object | | | | `fields[].default_value.value` | boolean \| null | | (Boolean) | | `fields[].default_value.value` | integer \| null | | (Integer) | | `fields[].default_value.value` | number \| null | | (Float) | | `fields[].default_value.value` | one of: string \| null \| array \| null | | (String) | | `fields[].default_value.value` | string \| null (date-time) | | (Datetime) | | `fields[].default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `fields[].description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `fields[].display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `fields[].field_options` | array \| null | | The fixed list of value options that may be stored in this field. | | `fields[].field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `fields[].id` | string | yes | The ID of the resource. Read-only. | | `fields[].name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `fields[].self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `fields[].summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `fields[].type` | string | yes | Read-only. One of: `field`. | | `fields[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | Example: Response Example ```json { "fields": [ { "id": "P5IYCNZ", "type": "field", "summary": "environment", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "environment", "display_name": "Environment", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z", "default_value": null, "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "abc" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/update-custom-fields-field # Update a Field `PUT https://api.pagerduty.com/incidents/custom_fields/{field_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/update-incident-type-custom-field) Update a Custom Field on the Base Incident Type. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | Example: Request Example ```json { "field": { "display_name": "New Display Name!", "description": "New description!" } } ``` ## Response 200 The field object updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | Same fields as `field.default_value` above. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | Example: Response Example ```json { "field": { "id": "P5IYCNZ", "type": "field", "summary": "old_name", "self": "https://api.pagerduty.com/incidents/custom_fields/P5IYCNZ", "data_type": "string", "name": "old_name", "display_name": "New Display Name!", "description": "New description!", "field_type": "single_value", "default_value": null, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-custom-fields/update-custom-fields-field-option # Update a Field Option `PUT https://api.pagerduty.com/incidents/custom_fields/{field_id}/field_options/{field_option_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated and only works for fields on the Base Incident Type. \ > For more flexibility, we recommend using the Incident Types endpoint: \ > [/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options/{field_option_id}](https://docs.pagerduty.com/developer/api/reference/rest/incident-types/update-incident-type-custom-field-field-option) Update a Field Option for a Custom Field on the Base Incident Type. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | | `field_option_id` | string | yes | The ID of the field option. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "prod" } } } ``` ## Response 200 The field option object updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | yes | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_option": { "id": "PQ9K7I8", "type": "field_option", "data": { "data_type": "string", "value": "prod" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/create-incident-type # Create an Incident Type `POST https://api.pagerduty.com/incidents/types` Create a new incident type. Incident Types are a feature which will allow customers to categorize incidents, such as a security incident, a major incident, or a fraud incident. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidentType) Scoped OAuth requires: `incident_types.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident_type` | object | yes | Details of the incident type to be created. | | `incident_type.name` | string | yes | The name of the Incident Type. Usage of the suffix `_default` is prohibited. This cannot be changed once the incident type has been created. Max length: 50. | | `incident_type.display_name` | string | yes | The display name of the Incident Type. Usage of the prefix `PD`, `PagerDuty`, `Default` is prohibited. Max length: 50. | | `incident_type.parent_type` | string | yes | The parent type of the Incident Type. Either name or id of the parent type can be used. | | `incident_type.enabled` | boolean | | Whether the Incident Type is enabled. Defaults to true if not provided. | | `incident_type.description` | string | | The description of the Incident Type. Max length: 1000. | Example: Request Example ```json { "incident_type": { "name": "fraud_incident", "display_name": "Fraud Incident", "parent_type": "incident_default" } } ``` ## Response 201 The incident type object created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_type` | object | yes | | | `incident_type.enabled` | boolean | | State of this Incident Type object. | | `incident_type.id` | string | | Read-only. | | `incident_type.name` | string | | The name of the Incident Type. | | `incident_type.parent` | object | | The parent Incident Type (id/name). If omitted, type is created under top level (incident_default) | | `incident_type.parent.id` | string | | | | `incident_type.parent.type` | string | | | | `incident_type.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident_type.description` | string | | A succinct description of the Incident Type. | | `incident_type.created_at` | string (date-time) | | The time the Incident Type was created. Read-only. | | `incident_type.updated_at` | string (date-time) | | The time the Incident Type was last modified. | | `incident_type.display_name` | string | | The display name of the Incident Type. The first character must be alphanumeric. Max length: 50, Min Length : 1. The `display_name` for a Field must be unique. | Example: Response Example ```json { "incident_type": { "enabled": true, "id": "P234567", "name": "fraud_incident", "parent": { "id": "P123456", "type": "incident_type_reference" }, "type": "incident_type", "description": null, "created_at": "2023-05-31T13:41:47Z", "updated_at": "2023-07-31T13:41:47Z", "display_name": "Fraud Incident" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/create-incident-type-custom-field # Create a Custom Field for an Incident Type `POST https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields` Create a Custom Field for an Incident Type Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Details of the custom field to be created. | | `field.name` | string | yes | The name of the custom field. Max length: 50. | | `field.display_name` | string | yes | The display name of the Incident Type. Max length: 50. | | `field.data_type` | string | yes | The data type of the custom field. | | `field.field_type` | string | yes | The field type of the custom field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.description` | string | | The description of the custom field. Max length: 1000. | | `field.enabled` | boolean | | Whether the custom field is enabled. | | `field.default_value` | string | | The default value of the custom field. | | `field.field_options` | array of object | | The options for the custom field. Can only be applied to fields with a `field_type` of `single_value_fixed` or `multi_value_fixed`. When creating a fixed-value custom field, this property is required, as the field must be created with at least one field option. | | `field.field_options[].data` | one of: object | yes | | | `field.field_options[].data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | yes | (option 1) Max length: 100. | | `field.field_options[].id` | string | yes | The ID of the resource. Read-only. | | `field.field_options[].type` | string | yes | Read-only. One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field.field_options[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Request Example ```json { "field": { "name": "custom_field_1", "display_name": "Custom Field 1", "data_type": "string", "field_type": "single_value" } } ``` Example: Example with Fixed Value Field ```json { "field": { "name": "development_environment", "display_name": "Development Environment", "description": "The environment that the issue occurred in", "data_type": "string", "field_type": "single_value_fixed", "field_options": [ { "data": { "data_type": "string", "value": "staging" } }, { "data": { "data_type": "string", "value": "production" } } ] } } ``` ## Response 201 The custom field object created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.enabled` | boolean | yes | Whether the custom field is enabled. Read-only. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.updated_at` | string (date-time) | yes | The date/time the custom field was last updated. Read-only. | | `field.created_at` | string (date-time) | yes | The date/time the custom field was created at. Read-only. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.incident_type` | string | yes | The id of the incident type the custom field is associated with. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `field.field_options` | array of object | yes | The options for the custom field. | | `field.field_options[].data` | one of: object | | | | `field.field_options[].data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | yes | (option 1) Max length: 100. | | `field.field_options[].id` | string | yes | The ID of the resource. Read-only. | | `field.field_options[].type` | string | yes | Read-only. One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field.field_options[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field": { "enabled": true, "id": "P123456", "name": "custom_field_1", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P567890/custom_fields/P123456", "description": null, "field_type": "single_value", "data_type": "string", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z", "display_name": "Custom Field 1", "default_value": null, "incident_type": "P567890", "summary": "custom_field_1" } } ``` Example: Example for Fixed-Value Field ```json { "field": { "enabled": true, "id": "P4567", "name": "development_environment", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P567890/custom_fields/P4567", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "data_type": "string", "updated_at": "2021-06-01T21:30:43Z", "created_at": "2021-06-01T21:30:43Z", "display_name": "Development Environment", "default_value": null, "incident_type": "P567890", "summary": "development_environment", "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:43Z", "updated_at": "2021-06-01T21:30:43Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/create-incident-type-custom-field-field-options # Create a Field Option for a Custom Field `POST https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options` Create a field option for a custom field. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | Details of the field option to be created. | | `field_option.data` | object | yes | | | `field_option.data.data_type` | string | yes | The data type of the Field Option for the Custom Field. | | `field_option.data.value` | string | yes | The value of the Field Option for the Custom Field. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "option_1" } } } ``` ## Response 201 The field option for the custom field created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_option": { "id": "P123456", "data": { "data_type": "string", "value": "option_1" }, "type": "field_option", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/delete-incident-type-custom-field # Delete a Custom Field for an Incident Type `DELETE https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}` Delete a custom field for an incident type. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The field was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/delete-incident-type-custom-field-field-option # Delete a Field Option for a Custom Field `DELETE https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options/{field_option_id}` Delete a field option for a custom field. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_option_id` | string | yes | The ID of the field option. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The field option was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/get-incident-type # Get an Incident Type `GET https://api.pagerduty.com/incidents/types/{type_id_or_name}` Get detailed information about a single incident type. Accepts either an incident type id, or an incident type name. Incident Types are a feature which will allow customers to categorize incidents, such as a security incident, a major incident, or a fraud incident. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incident) Scoped OAuth requires: `incident_types.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The incident type requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_type` | object | yes | | | `incident_type.enabled` | boolean | | State of this Incident Type object. | | `incident_type.id` | string | | Read-only. | | `incident_type.name` | string | | The name of the Incident Type. | | `incident_type.parent` | object | | The parent Incident Type (id/name). If omitted, type is created under top level (incident_default) | | `incident_type.parent.id` | string | | | | `incident_type.parent.type` | string | | | | `incident_type.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident_type.description` | string | | A succinct description of the Incident Type. | | `incident_type.created_at` | string (date-time) | | The time the Incident Type was created. Read-only. | | `incident_type.updated_at` | string (date-time) | | The time the Incident Type was last modified. | | `incident_type.display_name` | string | | The display name of the Incident Type. The first character must be alphanumeric. Max length: 50, Min Length : 1. The `display_name` for a Field must be unique. | Example: Response Example ```json { "incident_type": { "enabled": true, "id": "P567890", "parent": { "id": "P123456", "type": "incident_type_reference" }, "name": "major_incident", "type": "incident_type", "description": "Major incidents", "created_at": "2023-05-31T13:41:47Z", "updated_at": "2023-07-31T13:41:47Z", "display_name": "Major Incident" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/get-incident-type-custom-field # Get an Incident Type Custom Field `GET https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}` Get a custom field for an incident type. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_id` | string | yes | The ID of the field. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The incident type custom field requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.enabled` | boolean | yes | Whether the custom field is enabled. Read-only. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.incident_type` | string | yes | The id of the incident type the custom field is associated with. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `field.field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. Optionally included in response based on query parameter. | | `field.field_options[].id` | string | | | | `field.field_options[].type` | string | | One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | | The date/time the field option was last updated. Read-only. | | `field.field_options[].created_at` | string (date-time) | | The date/time the field option was created at. Read-only. | | `field.field_options[].data` | object | | | | `field.field_options[].data.value` | string | | | | `field.field_options[].data.data_type` | | | One of: `string`. | Example: Response Example - No query parameter ```json { "field": { "enabled": true, "id": "P123456", "name": "environment", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P567890/custom_fields/P123456", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "data_type": "string", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z", "display_name": "Environment", "default_value": null, "incident_type": "P567890", "summary": "environment" } } ``` Example: Response Example - Include field options ```json { "field": { "enabled": true, "id": "P123456", "name": "environment", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P567890/custom_fields/P123456", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "data_type": "string", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z", "display_name": "Environment", "default_value": null, "incident_type": "P567890", "summary": "environment", "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/get-incident-type-custom-field-field-options # Get a Field Option on a Custom Field `GET https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options/{field_option_id}` Get a field option on a custom field Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_option_id` | string | yes | The ID of the field option. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The field option of the custom field requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_option": { "data": { "data_type": "string", "value": "option1" }, "id": "PQ9K7I8", "type": "field_option", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/list-incident-type-custom-field # List Field Options on a Custom Field `GET https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options` List field options for a custom field. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The field option for the custom field requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_options` | array of object | yes | | | `field_options[].data` | one of: object | yes | | | `field_options[].data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_options[].data.value` | string | yes | (option 1) Max length: 100. | | `field_options[].id` | string | yes | The ID of the resource. Read-only. | | `field_options[].type` | string | yes | Read-only. One of: `field_option`. | | `field_options[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_options[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_options": [ { "data": { "data_type": "string", "value": "option1" }, "id": "PQ9K7I8", "type": "field_option", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z" }, { "data": { "data_type": "string", "value": "option2" }, "id": "PZ9K7I9", "type": "field_option", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/list-incident-type-custom-fields # List Incident Type Custom Fields `GET https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields` List the custom fields for an incident type. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The custom fields for the incident type requested. Passing in include[]=field_options will return the field options for the custom field. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `fields` | array of object | yes | | | `fields[].enabled` | boolean | yes | Whether the custom field is enabled. Read-only. | | `fields[].id` | string | yes | The ID of the resource. Read-only. | | `fields[].name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `fields[].type` | string | yes | Read-only. One of: `field`. | | `fields[].self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `fields[].description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `fields[].field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `fields[].data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `fields[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `fields[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `fields[].display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `fields[].default_value` | one of: object \| object \| object \| object \| object \| object | | | | `fields[].default_value.value` | boolean \| null | | (Boolean) | | `fields[].default_value.value` | integer \| null | | (Integer) | | `fields[].default_value.value` | number \| null | | (Float) | | `fields[].default_value.value` | one of: string \| null \| array \| null | | (String) | | `fields[].default_value.value` | string \| null (date-time) | | (Datetime) | | `fields[].default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `fields[].incident_type` | string | yes | The id of the incident type the custom field is associated with. Read-only. | | `fields[].summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `fields[].field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. Optionally included in response based on query parameter. | | `fields[].field_options[].id` | string | | | | `fields[].field_options[].type` | string | | One of: `field_option`. | | `fields[].field_options[].updated_at` | string (date-time) | | The date/time the field option was last updated. Read-only. | | `fields[].field_options[].created_at` | string (date-time) | | The date/time the field option was created at. Read-only. | | `fields[].field_options[].data` | object | | | | `fields[].field_options[].data.value` | string | | | | `fields[].field_options[].data.data_type` | | | One of: `string`. | Example: Response Example - No query parameters ```json { "fields": [ { "enabled": true, "id": "P567890", "name": "incident_commander", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P123456/custom_fields/P567890", "description": "field description", "field_type": "single_value_fixed", "data_type": "string", "created_at": "2023-05-31T13:41:47Z", "updated_at": "2023-07-31T13:41:47Z", "display_name": "Incident Commander", "default_value": "John Doe", "incident_type": "Security Incident", "summary": "incident_commander" }, { "enabled": true, "id": "P456789", "name": "due_date", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P123456/custom_fields/P456789", "description": "field description", "field_type": "single_value", "data_type": "string", "created_at": "2024-05-31T13:41:47Z", "updated_at": "2024-07-31T13:41:47Z", "display_name": "Due Date", "default_value": "2025-07-31T13:41:47Z", "incident_type": "Security Incident 2", "summary": "due_date" } ] } ``` Example: Response Example - Include field options ```json { "fields": [ { "enabled": true, "id": "P567890", "name": "incident_commander", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P123456/custom_fields/P567890", "description": "field description", "field_type": "single_value_fixed", "data_type": "string", "created_at": "2023-05-31T13:41:47Z", "updated_at": "2023-07-31T13:41:47Z", "display_name": "Incident Commander", "default_value": "John Doe", "incident_type": "Security Incident", "summary": "incident_commander", "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "John Doe" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "Jane Smith" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] }, { "enabled": true, "id": "P456789", "name": "due_date", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P123456/custom_fields/P456789", "description": "field description", "field_type": "single_value", "data_type": "string", "created_at": "2024-05-31T13:41:47Z", "updated_at": "2024-07-31T13:41:47Z", "display_name": "Due Date", "default_value": "2025-07-31T13:41:47Z", "incident_type": "Security Incident 2", "summary": "due_date" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/list-incident-types # List incident types `GET https://api.pagerduty.com/incidents/types` List the available incident types Incident Types are a feature which will allow customers to categorize incidents, such as a security incident, a major incident, or a fraud incident. These can be filtered by enabled or disabled types. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidentType) Scoped OAuth requires: `incident_types.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `filter` | string | | Filters the list of incident types based on their `enabled` state. One of: `enabled`, `disabled`, `all`. Default: `enabled`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of all types for the account. The default incident type will automatically return on this list. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_types` | array of object | yes | | | `incident_types[].enabled` | boolean | | State of this Incident Type object. | | `incident_types[].id` | string | | Read-only. | | `incident_types[].name` | string | | The name of the Incident Type. | | `incident_types[].parent` | object | | The parent Incident Type (id/name). If omitted, type is created under top level (incident_default) | | `incident_types[].parent.id` | string | | | | `incident_types[].parent.type` | string | | | | `incident_types[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident_types[].description` | string | | A succinct description of the Incident Type. | | `incident_types[].created_at` | string (date-time) | | The time the Incident Type was created. Read-only. | | `incident_types[].updated_at` | string (date-time) | | The time the Incident Type was last modified. | | `incident_types[].display_name` | string | | The display name of the Incident Type. The first character must be alphanumeric. Max length: 50, Min Length : 1. The `display_name` for a Field must be unique. | Example: Response Example ```json { "incident_types": [ { "type": "incident_type", "name": "incident_default", "id": "P123456", "created_at": "2023-05-31T13:40:47.000Z", "updated_at": "2023-07-31T13:40:47.000Z", "description": null, "display_name": "Base Incident", "enabled": true, "parent": null }, { "type": "incident_type", "name": "security", "id": "P567890", "created_at": "2023-05-31T13:41:47.000Z", "updated_at": "2023-07-31T13:40:47.000Z", "description": "Security related incidents", "display_name": "Security", "enabled": true, "parent": { "id": "P123456", "type": "incident_type_reference" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/update-incident-type # Update an Incident Type `PUT https://api.pagerduty.com/incidents/types/{type_id_or_name}` Update an Incident Type. Incident Types are a feature which will allow customers to categorize incidents, such as a security incident, a major incident, or a fraud incident. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incident) Scoped OAuth requires: `incident_types.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident_type` | object | yes | Details of the incident type to be created. | | `incident_type.display_name` | string | | The display name of the Incident Type. Max length: 50. | | `incident_type.enabled` | boolean | | Whether the Incident Type is enabled. Defaults to true if not provided. | | `incident_type.description` | string | | The description of the Incident Type. Max length: 1000. | Example: Request Example ```json { "incident_type": { "display_name": "Major Incident" } } ``` ## Response 200 The incident type object updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_type` | object | yes | | | `incident_type.enabled` | boolean | | State of this Incident Type object. | | `incident_type.id` | string | | Read-only. | | `incident_type.name` | string | | The name of the Incident Type. | | `incident_type.parent` | object | | The parent Incident Type (id/name). If omitted, type is created under top level (incident_default) | | `incident_type.parent.id` | string | | | | `incident_type.parent.type` | string | | | | `incident_type.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident_type.description` | string | | A succinct description of the Incident Type. | | `incident_type.created_at` | string (date-time) | | The time the Incident Type was created. Read-only. | | `incident_type.updated_at` | string (date-time) | | The time the Incident Type was last modified. | | `incident_type.display_name` | string | | The display name of the Incident Type. The first character must be alphanumeric. Max length: 50, Min Length : 1. The `display_name` for a Field must be unique. | Example: Response Example ```json { "incident_type": { "name": "major_incident", "id": "P567890", "created_at": "2023-05-31T13:41:47Z", "updated_at": "2023-07-31T13:41:47Z", "description": "Major incidents", "display_name": "Major Incident", "enabled": true, "parent": { "id": "P123456", "type": "incident_type_reference" }, "type": "incident_type" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/update-incident-type-custom-field # Update a Custom Field for an Incident Type `PUT https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}` Update a custom field for an incident type. Field Options can also be updated within the same call. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Details of the custom field to be updated. | | `field.display_name` | string | | The display name of the Incident Type. Max length: 50. | | `field.enabled` | boolean | | Whether the Incident Type is enabled. | | `field.default_value` | string | | The default value of the custom field. | | `field.description` | string | | The description of the custom field. Max length: 1000. | | `field.field_options` | array of object | | List of options to upsert on the custom field. Can only be applied to fields with a `field_type` of `single_value_fixed` or `multi_value_fixed`. When an `id` property is included, this will update the value of the specified field option. Without an `id` property, that field option will be added to the field. Any existing field options not included in the upsert list will be deleted (unless the current default value refers to a field option to be deleted). | | `field.field_options[].data` | one of: object | yes | | | `field.field_options[].data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | yes | (option 1) Max length: 100. | | `field.field_options[].id` | string | yes | The ID of the resource. Read-only. | | `field.field_options[].type` | string | yes | Read-only. One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field.field_options[].created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Request Example ```json { "field": { "display_name": "Custom Field 1" } } ``` Example: Example Updating a Field Option Together With Field Metadata ```json { "field": { "display_name": "Single Select Field Updated", "field_options": [ { "data": { "data_type": "string", "value": "Updated value for an existing field option" }, "id": "PQ9K7I8" }, { "data": { "data_type": "string", "value": "Upserting a brand new field option, by not providing an id property" } } ] } } ``` ## Response 200 The updated custom field object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | | | `field.enabled` | boolean | yes | Whether the custom field is enabled. Read-only. | | `field.id` | string | yes | The ID of the resource. Read-only. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.type` | string | yes | Read-only. One of: `field`. | | `field.self` | string \| null (url) | yes | The API show URL at which the object is accessible. Read-only. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.default_value` | one of: object \| object \| object \| object \| object \| object | | | | `field.default_value.value` | boolean \| null | | (Boolean) | | `field.default_value.value` | integer \| null | | (Integer) | | `field.default_value.value` | number \| null | | (Float) | | `field.default_value.value` | one of: string \| null \| array \| null | | (String) | | `field.default_value.value` | string \| null (date-time) | | (Datetime) | | `field.default_value.value` | string \| null (uri) | | (Url) Max length: 200. | | `field.incident_type` | string | yes | The id of the incident type the custom field is associated with. Read-only. | | `field.summary` | string \| null | yes | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `field.field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. Optionally included in response based on query parameter. | | `field.field_options[].id` | string | | | | `field.field_options[].type` | string | | One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | | The date/time the field option was last updated. Read-only. | | `field.field_options[].created_at` | string (date-time) | | The date/time the field option was created at. Read-only. | | `field.field_options[].data` | object | | | | `field.field_options[].data.value` | string | | | | `field.field_options[].data.data_type` | | | One of: `string`. | Example: Response Example ```json { "field": { "enabled": true, "id": "P123456", "name": "custom_field_1", "type": "field", "self": "https://api.pagerduty.com/incidents/types/P567890/custom_fields/P123456", "description": "The environment that the issue occurred in", "field_type": "single_value_fixed", "data_type": "string", "updated_at": "2021-06-01T21:30:42Z", "created_at": "2021-06-01T21:30:42Z", "display_name": "Custom Field 1", "default_value": null, "incident_type": "P567890", "summary": "custom_field_1", "field_options": [ { "id": "PT4KHEE", "type": "field_option", "data": { "data_type": "string", "value": "production" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" }, { "id": "P5IYCNZ", "type": "field_option", "data": { "data_type": "string", "value": "staging" }, "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-types/update-incident-type-custom-field-field-option # Update a Field Option for a Custom Field `PUT https://api.pagerduty.com/incidents/types/{type_id_or_name}/custom_fields/{field_id}/field_options/{field_option_id}` Update a field option for a custom field. Custom Fields (CF) are a feature which will allow customers to extend Incidents with their own custom data, to provide additional context and support features such as customized filtering, search and analytics. Custom Fields can be applied to different incident types. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `type_id_or_name` | string | yes | The ID or name of the Incident Type. | | `field_option_id` | string | yes | The ID of the field option. | | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | Details of the field option on a custom field to be updated. | | `field_option.data` | object | yes | | | `field_option.data.data_type` | string | yes | The data type of the Field Option on the Custom Field. | | `field_option.data.value` | string | yes | The value of the Field Option on the Custom Field. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "option_1" } } } ``` ## Response 200 The field option for the custom field updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | | | `field_option.data` | one of: object | | | | `field_option.data.data_type` | string | yes | (option 1) The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | (option 1) Max length: 100. | | `field_option.id` | string | yes | The ID of the resource. Read-only. | | `field_option.type` | string | yes | Read-only. One of: `field_option`. | | `field_option.updated_at` | string (date-time) | yes | The date/time the object was last updated. Read-only. | | `field_option.created_at` | string (date-time) | yes | The date/time the object was created at. Read-only. | Example: Response Example ```json { "field_option": { "data": { "data_type": "string", "value": "option_1" }, "id": "P123456", "type": "field_option", "created_at": "2021-06-01T21:30:42Z", "updated_at": "2021-06-01T21:30:42Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/associate-service-to-incident-workflow-trigger # Associate a Trigger and Service `POST https://api.pagerduty.com/incident_workflows/triggers/{id}/services` Associate a Service with an existing Incident Workflow Trigger Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | | | `service.id` | string | | | Example: Request Example ```json { "service": { "id": "PIJ90N7" } } ``` ## Response 201 The updated Incident Workflow Trigger ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `trigger.workflow.name` | string | | A descriptive name for the Incident Workflow. | | `trigger.workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `trigger.services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `trigger.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "trigger": { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Conditional Trigger", "trigger_type": "conditional", "condition": "incident.priority matches 'P1'", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": false, "services": [ { "id": "PIJ90N7", "summary": "My Application Service", "type": "service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://pdt-circular.pagerduty.com/service-directory/P0544JX" } ], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://mydomain.pagerduty.com/flex-workflows/workflows/PSFEVL7" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/create-incident-workflow-instance # Start an Incident Workflow Instance `POST https://api.pagerduty.com/incident_workflows/{id}/instances` Start an Instance of an Incident Workflow. Sometimes referred to as "triggering a workflow on an incident." An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows:instances.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow_instance` | object | yes | | | `incident_workflow_instance.id` | string | | An identifier to help differentiate between workflow executions. | | `incident_workflow_instance.incident` | object | | | | `incident_workflow_instance.incident.id` | string | yes | | | `incident_workflow_instance.incident.type` | string | | One of: `incident_reference`. | Example: Request Example ```json { "incident_workflow_instance": { "id": "P3SNKQS", "type": "incident_workflow_instance", "incident": { "id": "Q1R2DLCB21K7NP", "type": "incident_reference" } } } ``` ## Response 201 The Incident Workflow Instance ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow_instance` | object | yes | | | `incident_workflow_instance.id` | string | | Read-only. | | `incident_workflow_instance.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. One of: `incident_workflow_instance`. | | `incident_workflow_instance.incident` | object | | | | `incident_workflow_instance.incident.id` | string | yes | Read-only. | | `incident_workflow_instance.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow_instance.incident.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident_workflow_instance.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow_instance.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "incident_workflow_instance": { "id": "P3SNKQS", "type": "incident_workflow_instance", "incident": { "id": "Q1R2DLCB21K7NP", "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" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/create-incident-workflow-trigger # Create a Trigger `POST https://api.pagerduty.com/incident_workflows/triggers` Create new Incident Workflow Trigger Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. A previous API version allowed callers to set this property independently. This behavior is deprecated. This property's value will be set based on the "is_enabled" property of the workflow to which this trigger belongs. **Deprecated.** | Example: Request Example ```json { "trigger": { "trigger_type": "conditional", "workflow": { "id": "PSFEVL7" }, "services": [ { "id": "PIJ90N7" } ], "is_subscribed_to_all_services": false, "condition": "incident.priority matches 'P1'" } } ``` ## Response 201 The newly created Incident Workflow Trigger ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `trigger.workflow.name` | string | | A descriptive name for the Incident Workflow. | | `trigger.workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `trigger.services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `trigger.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "trigger": { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Conditional Trigger", "trigger_type": "conditional", "condition": "incident.priority matches 'P1'", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": false, "services": [ { "id": "PIJ90N7", "summary": "My Application Service", "type": "service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://pdt-circular.pagerduty.com/service-directory/P0544JX" } ], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://mydomain.pagerduty.com/flex-workflows/workflows/PSFEVL7" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/delete-incident-workflow # Delete an Incident Workflow `DELETE https://api.pagerduty.com/incident_workflows/{id}` Delete an existing Incident Workflow An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Incident Workflow was deleted successfully ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/delete-incident-workflow-trigger # Delete a Trigger `DELETE https://api.pagerduty.com/incident_workflows/triggers/{id}` Delete an existing Incident Workflow Trigger Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Incident Workflow Trigger was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/delete-service-from-incident-workflow-trigger # Dissociate a Trigger and Service `DELETE https://api.pagerduty.com/incident_workflows/triggers/{trigger_id}/services/{service_id}` Remove a an existing Service from an Incident Workflow Trigger Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `trigger_id` | string | yes | Identifier for the Trigger. | | `service_id` | string | yes | Identifier for the Service. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 201 The updated Incident Workflow Trigger ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `trigger.workflow.name` | string | | A descriptive name for the Incident Workflow. | | `trigger.workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `trigger.services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `trigger.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "trigger": { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Conditional Trigger", "trigger_type": "conditional", "condition": "incident.priority matches 'P1'", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": false, "services": [], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://mydomain.pagerduty.com/flex-workflows/workflows/PSFEVL7" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/get-incident-workflow # Get an Incident Workflow `GET https://api.pagerduty.com/incident_workflows/{id}` Get an existing Incident Workflow An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 201 The Incident Workflow ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow` | object | yes | | | `incident_workflow.id` | string | | Read-only. | | `incident_workflow.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.type` | string | | One of: `incident_workflow`. | | `incident_workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.name` | string | | A descriptive name for the Incident Workflow. | | `incident_workflow.description` | string | | A description of what the Incident Workflow does. | | `incident_workflow.created_at` | string (date-time) | | The timestamp this Incident Workflow was created. Read-only. | | `incident_workflow.team` | object | | If specified then workflow edit permissions will be scoped to members of this team. | | `incident_workflow.team.type` | string | | Type of the referenced object. Read-only. One of: `team_reference`. | | `incident_workflow.team.id` | string | | Unique identifier for the resource. Read-only. | | `incident_workflow.is_enabled` | boolean | | Indicates whether the Incident Workflow is enabled or not. Disabled workflows will not be triggered, and will not count toward the account's enabled workflow limit. Default: `true`. | | `incident_workflow.steps` | array of object | | The ordered list of steps that execute sequentially as part of the workflow. | | `incident_workflow.steps[].id` | string | | Read-only. | | `incident_workflow.steps[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.steps[].type` | string | | One of: `step`. | | `incident_workflow.steps[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.steps[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.steps[].name` | string | yes | A descriptive name for the Step. | | `incident_workflow.steps[].description` | string | | A description of the action performed by the Step. Read-only. | | `incident_workflow.steps[].action_configuration` | object | yes | Configuration of automated action executed by this Step. | | `incident_workflow.steps[].action_configuration.action_id` | string | yes | The identifier of the Action to execute. | | `incident_workflow.steps[].action_configuration.description` | string | | Description of the Action. Read-only. | | `incident_workflow.steps[].action_configuration.inputs` | array of object | yes | An unordered list of standard inputs used to configure the Action to execute. | | `incident_workflow.steps[].action_configuration.inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inputs[].parameter_type` | string | | The data type of this Input. Read-only. | | `incident_workflow.steps[].action_configuration.inputs[].value` | string | yes | The configured value of the Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs` | array of object | | An unordered list of specialized inputs used to configure a workflow-within-a-workflow. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value` | object | yes | The configured value of the Inline Steps Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value.steps` | array of object | | | | `incident_workflow.steps[].action_configuration.outputs` | array of object | | An unordered list of outputs this action produces. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].name` | string | yes | The name for this Output. Output names are unique per action and should be used to find a specific Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].reference_name` | string | | The reference name of the Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].parameter_type` | string | | The data type produced by this Output. Read-only. | Example: Response Example ```json { "incident_workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7", "steps": [ { "id": "P4RG7YW", "type": "step", "name": "Send Status Update", "description": "Posts a status update to a given incident", "action_configuration": { "action_id": "pagerduty.com:incident-workflows:send-status-update:1", "description": "Posts a status update to a given incident", "inputs": [ { "name": "Message", "parameter_type": "text", "value": "Example status message sent on {{current_date}}" } ], "outputs": [ { "name": "Result", "reference_name": "result", "parameter_type": "text" }, { "name": "Result Summary", "reference_name": "result-summary", "parameter_type": "text" }, { "name": "Error", "reference_name": "error", "parameter_type": "text" } ] } } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/get-incident-workflow-action # Get an Action `GET https://api.pagerduty.com/incident_workflows/actions/{id}` Get an Incident Workflow Action Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An Incident Workflow Action ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `action` | object | | | | `action.id` | string | | Read-only. | | `action.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `action.type` | string | | One of: `action`. | | `action.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `action.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `action.domain_name` | string | | The Verified Domain of the account that created the action. | | `action.package_name` | string | | The Package Name corresponding to the broad category of the Action. | | `action.function_name` | string | | The Function Name describing the specific functionality of the Action. | | `action.version` | number | | The version of the Action. | | `action.name` | string | | The descriptive name of the Action. | | `action.description` | string | | A description of the Action. | | `action.action_type` | string | | The type of Action. One of: `action`, `trigger`. | | `action.action_tier` | string | | The tier of the Action. One of: `basic-action`, `standard-action`, `premium-action`. | | `action.trigger_type` | string | | The type of Trigger this Action is, if action_type is trigger. One of: `polling`, `subscription`, `web`. | | `action.tags` | array of string | | A set of tags to apply to this action. | | `action.search_keywords` | array of string | | A set of search keywords to apply to this action. | | `action.metadata` | string | | JSON-formatted string of metadata pertaining to the Action. | | `action.created_at` | string (date-time) | | The date-time at which this Action was created. | | `action.created_by_user_id` | string | | The obfuscated Id of the User who created this Action. | | `action.inputs` | array of object | | Inputs whose values used during Action execution. | | `action.inputs[].name` | string | | The name of the Input. | | `action.inputs[].description` | string | | Describes what the purpose of the Input. | | `action.inputs[].type` | string | | The data type of this Input. One of: `text`, `password`, `integer`, `decimal`, `date`, `dateTime`, `boolean`, `singleChoice`, `multipleChoice`, `json`, `connection`, `trigger`. | | `action.inputs[].default_value` | string | | Serialized form of the default value that the input will take. | | `action.inputs[].is_required` | boolean | | Whether a value must be provided for this input. | | `action.inputs[].is_hidden` | boolean | | If true then this input will not be shown to users when configuring this action. | | `action.inputs[].advanced` | boolean | | | | `action.inputs[].metadata` | string | | | | `action.inputs[].connection_type_id` | string | | The configured value of the Input. | | `action.outputs` | array of object | | Outputs whose values set during Action execution. Read-only. | | `action.outputs[].name` | string | | The name of the Output. | | `action.outputs[].description` | string | | | | `action.outputs[].type` | string | | The data type produced by this Output. One of: `text`, `password`, `integer`, `decimal`, `date`, `dateTime`, `boolean`, `singleChoice`, `multipleChoice`, `json`. | Example: Response Example ```json { "action": { "type": "action", "id": "pagerduty.com:test:sample-action:1", "domain_name": "pagerduty.com", "package_name": "test", "function_name": "sample-action", "version": 1, "name": "Test: Sample Action", "description": "A fake Action for documentation purposes", "action_type": "integration", "action_tier": "premium-action", "tags": [], "metadata": "{}", "search_keywords": [], "inputs": [ { "name": "Text Input", "description": "A text input", "type": "text", "default_value": "some text", "is_required": true, "is_hidden": false, "advanced": false, "metadata": "{}", "connection_type_id": "" }, { "name": "Int Input", "description": "An integer input", "type": "integer", "default_value": "1234", "is_required": false, "is_hidden": false, "advanced": false, "metadata": "{}", "connection_type_id": "" } ], "outputs": [ { "name": "Text Output", "description": "A text output", "type": "text" } ], "created_at": "2022-12-08T22:14:16.965Z", "created_by_user_id": "PNBURS9" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/get-incident-workflow-trigger # Get a Trigger `GET https://api.pagerduty.com/incident_workflows/triggers/{id}` Retrieve an existing Incident Workflows Trigger Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Incident Workflows Trigger ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `trigger.workflow.name` | string | | A descriptive name for the Incident Workflow. | | `trigger.workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `trigger.services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `trigger.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "trigger": { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Manual Trigger", "trigger_type": "manual", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": true, "services": [], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7" }, "permissions": { "restricted": true, "team_id": "PUOEV7R" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/list-incident-workflow-actions # List Actions `GET https://api.pagerduty.com/incident_workflows/actions` List Incident Workflow Actions Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `keyword` | string | | If provided, only show actions tagged with the specified keyword. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Incident Workflow Actions ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `actions` | array of object | | | | `actions[].id` | string | | Read-only. | | `actions[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `actions[].type` | string | | One of: `action`. | | `actions[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `actions[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `actions[].domain_name` | string | | The Verified Domain of the account that created the action. | | `actions[].package_name` | string | | The Package Name corresponding to the broad category of the Action. | | `actions[].function_name` | string | | The Function Name describing the specific functionality of the Action. | | `actions[].version` | number | | The version of the Action. | | `actions[].name` | string | | The descriptive name of the Action. | | `actions[].description` | string | | A description of the Action. | | `actions[].action_type` | string | | The type of Action. One of: `action`, `trigger`. | | `actions[].action_tier` | string | | The tier of the Action. One of: `basic-action`, `standard-action`, `premium-action`. | | `actions[].trigger_type` | string | | The type of Trigger this Action is, if action_type is trigger. One of: `polling`, `subscription`, `web`. | | `actions[].tags` | array of string | | A set of tags to apply to this action. | | `actions[].search_keywords` | array of string | | A set of search keywords to apply to this action. | | `actions[].metadata` | string | | JSON-formatted string of metadata pertaining to the Action. | | `actions[].created_at` | string (date-time) | | The date-time at which this Action was created. | | `actions[].created_by_user_id` | string | | The obfuscated Id of the User who created this Action. | | `actions[].inputs` | array of object | | Inputs whose values used during Action execution. | | `actions[].inputs[].name` | string | | The name of the Input. | | `actions[].inputs[].description` | string | | Describes what the purpose of the Input. | | `actions[].inputs[].type` | string | | The data type of this Input. One of: `text`, `password`, `integer`, `decimal`, `date`, `dateTime`, `boolean`, `singleChoice`, `multipleChoice`, `json`, `connection`, `trigger`. | | `actions[].inputs[].default_value` | string | | Serialized form of the default value that the input will take. | | `actions[].inputs[].is_required` | boolean | | Whether a value must be provided for this input. | | `actions[].inputs[].is_hidden` | boolean | | If true then this input will not be shown to users when configuring this action. | | `actions[].inputs[].advanced` | boolean | | | | `actions[].inputs[].metadata` | string | | | | `actions[].inputs[].connection_type_id` | string | | The configured value of the Input. | | `actions[].outputs` | array of object | | Outputs whose values set during Action execution. Read-only. | | `actions[].outputs[].name` | string | | The name of the Output. | | `actions[].outputs[].description` | string | | | | `actions[].outputs[].type` | string | | The data type produced by this Output. One of: `text`, `password`, `integer`, `decimal`, `date`, `dateTime`, `boolean`, `singleChoice`, `multipleChoice`, `json`. | Example: Response Example ```json { "actions": [ { "type": "action", "id": "pagerduty.com:test:sample-action:1", "domain_name": "pagerduty.com", "package_name": "test", "function_name": "sample-action", "version": 1, "name": "Test: Sample Action", "description": "A fake Action for documentation purposes", "action_type": "integration", "action_tier": "premium-action", "tags": [], "metadata": "{}", "search_keywords": [], "inputs": [ { "name": "Text Input", "description": "A text input", "type": "text", "default_value": "some text", "is_required": true, "is_hidden": false, "advanced": false, "metadata": "{}", "connection_type_id": "" }, { "name": "Int Input", "description": "An integer input", "type": "integer", "default_value": "1234", "is_required": false, "is_hidden": false, "advanced": false, "metadata": "{}", "connection_type_id": "" } ], "outputs": [ { "name": "Text Output", "description": "A text output", "type": "text" } ], "created_at": "2022-12-08T22:14:16.965Z", "created_by_user_id": "PNBURS9" } ], "limit": 1, "next_cursor": "N2E3YzkzNjMtYzBkMC00NjFmLTg1OTEtMGZjMjcwODUzODNl", "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/list-incident-workflow-triggers # List Triggers `GET https://api.pagerduty.com/incident_workflows/triggers` List existing Incident Workflow Triggers Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `workflow_id` | string | | If provided, only show triggers configured to start the given workflow. Useful for listing all services associated with the given workflow. | | `incident_id` | string | | If provided, only show triggers configured on the service of the given incident. Useful for finding manual triggers that are configured on the service for a specific incident. Cannot be specified if `service_id` is provided. | | `service_id` | string | | If provided, only show triggers configured for incidents in the given service. Useful for listing all workflows associated with the given service. Cannot be specified if `incident_id` is provided. | | `trigger_type` | string | | If provided, only show triggers of the given type. For example “manual” to search for manual triggers. One of: `manual`, `conditional`, `incident_type`. | | `workflow_name_contains` | string | | If provided, only show triggers configured to start workflows whose name contain the provided value. | | `is_disabled` | boolean | | **Deprecated.** If provided, filters between disabled and enabled Triggers. This query parameter is deprecated, and will be removed in a future version of this API. | | `sort_by` | string | | If provided, returns triggers sorted by the specified property. One of: `workflow_id`, `workflow_id asc`, `workflow_id desc`, `workflow_name`, `workflow_name asc`, `workflow_name desc`. | | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Incident Workflow Triggers ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `triggers` | array of object | | | | `triggers[].id` | string | | Read-only. | | `triggers[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `triggers[].type` | string | | One of: `workflow_trigger`. | | `triggers[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `triggers[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `triggers[].trigger_type_name` | string | | Human readable name for the trigger type. | | `triggers[].trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `triggers[].condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `triggers[].trigger_url` | string (url) | | | | `triggers[].incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `triggers[].workflow` | object | | Workflow to start when this trigger is invoked. | | `triggers[].workflow.id` | string | | | | `triggers[].workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `triggers[].workflow.name` | string | | A descriptive name for the Incident Workflow. | | `triggers[].workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `triggers[].workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `triggers[].services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `triggers[].services[].id` | string | | | | `triggers[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `triggers[].services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `triggers[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `triggers[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `triggers[].is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `triggers[].permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `triggers[].permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `triggers[].permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `triggers[].is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "triggers": [ { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Conditional Trigger", "trigger_type": "conditional", "condition": "incident.priority matches 'P1'", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": true, "services": [], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7" }, "permissions": { "restricted": false } } ], "limit": 1, "next_cursor": "N2E3YzkzNjMtYzBkMC00NjFmLTg1OTEtMGZjMjcwODUzODNl", "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/list-incident-workflows # List Incident Workflows `GET https://api.pagerduty.com/incident_workflows` List existing Incident Workflows. This is the best method to use to list all Incident Workflows in your account. If your use case requires listing Incident Workflows associated with a particular Service, you can use the "List Triggers" method to find Incident Workflows configured to start for Incidents in a given Service. An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `include[]` | string | | Array of additional details to include. One of: `steps`, `team`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Incident Workflows. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `incident_workflows` | array of object | yes | | | `incident_workflows[].id` | string | | Read-only. | | `incident_workflows[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflows[].type` | string | | One of: `incident_workflow`. | | `incident_workflows[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflows[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflows[].name` | string | | A descriptive name for the Incident Workflow. | | `incident_workflows[].description` | string | | A description of what the Incident Workflow does. | | `incident_workflows[].created_at` | string (date-time) | | The timestamp this Incident Workflow was created. Read-only. | | `incident_workflows[].team` | object | | If specified then workflow edit permissions will be scoped to members of this team. | | `incident_workflows[].team.type` | string | | Type of the referenced object. Read-only. One of: `team_reference`. | | `incident_workflows[].team.id` | string | | Unique identifier for the resource. Read-only. | | `incident_workflows[].is_enabled` | boolean | | Indicates whether the Incident Workflow is enabled or not. Disabled workflows will not be triggered, and will not count toward the account's enabled workflow limit. Default: `true`. | | `incident_workflows[].steps` | array of object | | The ordered list of steps that execute sequentially as part of the workflow. | | `incident_workflows[].steps[].id` | string | | Read-only. | | `incident_workflows[].steps[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflows[].steps[].type` | string | | One of: `step`. | | `incident_workflows[].steps[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflows[].steps[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflows[].steps[].name` | string | yes | A descriptive name for the Step. | | `incident_workflows[].steps[].description` | string | | A description of the action performed by the Step. Read-only. | | `incident_workflows[].steps[].action_configuration` | object | yes | Configuration of automated action executed by this Step. | | `incident_workflows[].steps[].action_configuration.action_id` | string | yes | The identifier of the Action to execute. | | `incident_workflows[].steps[].action_configuration.description` | string | | Description of the Action. Read-only. | | `incident_workflows[].steps[].action_configuration.inputs` | array of object | yes | An unordered list of standard inputs used to configure the Action to execute. | | `incident_workflows[].steps[].action_configuration.inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflows[].steps[].action_configuration.inputs[].parameter_type` | string | | The data type of this Input. Read-only. | | `incident_workflows[].steps[].action_configuration.inputs[].value` | string | yes | The configured value of the Input. | | `incident_workflows[].steps[].action_configuration.inline_steps_inputs` | array of object | | An unordered list of specialized inputs used to configure a workflow-within-a-workflow. | | `incident_workflows[].steps[].action_configuration.inline_steps_inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflows[].steps[].action_configuration.inline_steps_inputs[].value` | object | yes | The configured value of the Inline Steps Input. | | `incident_workflows[].steps[].action_configuration.inline_steps_inputs[].value.steps` | array of object | | | | `incident_workflows[].steps[].action_configuration.outputs` | array of object | | An unordered list of outputs this action produces. Read-only. | | `incident_workflows[].steps[].action_configuration.outputs[].name` | string | yes | The name for this Output. Output names are unique per action and should be used to find a specific Output. Read-only. | | `incident_workflows[].steps[].action_configuration.outputs[].reference_name` | string | | The reference name of the Output. Read-only. | | `incident_workflows[].steps[].action_configuration.outputs[].parameter_type` | string | | The data type produced by this Output. Read-only. | Example: Response Example ```json { "incident_workflows": [ { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7" } ], "limit": 1, "offset": 0, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/post-incident-workflow # Create an Incident Workflow `POST https://api.pagerduty.com/incident_workflows` Create a new Incident Workflow An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow` | object | yes | | | `incident_workflow.id` | string | | Read-only. | | `incident_workflow.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.type` | string | | One of: `incident_workflow`. | | `incident_workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.name` | string | | A descriptive name for the Incident Workflow. | | `incident_workflow.description` | string | | A description of what the Incident Workflow does. | | `incident_workflow.created_at` | string (date-time) | | The timestamp this Incident Workflow was created. Read-only. | | `incident_workflow.team` | object | | If specified then workflow edit permissions will be scoped to members of this team. | | `incident_workflow.team.type` | string | | Type of the referenced object. Read-only. One of: `team_reference`. | | `incident_workflow.team.id` | string | | Unique identifier for the resource. Read-only. | | `incident_workflow.is_enabled` | boolean | | Indicates whether the Incident Workflow is enabled or not. Disabled workflows will not be triggered, and will not count toward the account's enabled workflow limit. Default: `true`. | | `incident_workflow.steps` | array of object | | The ordered list of steps that execute sequentially as part of the workflow. | | `incident_workflow.steps[].id` | string | | Read-only. | | `incident_workflow.steps[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.steps[].type` | string | | One of: `step`. | | `incident_workflow.steps[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.steps[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.steps[].name` | string | yes | A descriptive name for the Step. | | `incident_workflow.steps[].description` | string | | A description of the action performed by the Step. Read-only. | | `incident_workflow.steps[].action_configuration` | object | yes | Configuration of automated action executed by this Step. | | `incident_workflow.steps[].action_configuration.action_id` | string | yes | The identifier of the Action to execute. | | `incident_workflow.steps[].action_configuration.description` | string | | Description of the Action. Read-only. | | `incident_workflow.steps[].action_configuration.inputs` | array of object | yes | An unordered list of standard inputs used to configure the Action to execute. | | `incident_workflow.steps[].action_configuration.inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inputs[].parameter_type` | string | | The data type of this Input. Read-only. | | `incident_workflow.steps[].action_configuration.inputs[].value` | string | yes | The configured value of the Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs` | array of object | | An unordered list of specialized inputs used to configure a workflow-within-a-workflow. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value` | object | yes | The configured value of the Inline Steps Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value.steps` | array of object | | | | `incident_workflow.steps[].action_configuration.outputs` | array of object | | An unordered list of outputs this action produces. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].name` | string | yes | The name for this Output. Output names are unique per action and should be used to find a specific Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].reference_name` | string | | The reference name of the Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].parameter_type` | string | | The data type produced by this Output. Read-only. | Example: Request Example ```json { "incident_workflow": { "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "steps": [ { "name": "Send Status Update", "action_configuration": { "action_id": "pagerduty.com:incident-workflows:send-status-update:1", "inputs": [ { "name": "Message", "value": "Example status message sent on {{current_date}}" } ] } } ] } } ``` ## Response 201 The new Incident Workflow ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow` | object | yes | Same fields as `incident_workflow` above. | Example: Response Example ```json { "incident_workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7", "steps": [ { "id": "P4RG7YW", "type": "step", "name": "Send Status Update", "description": "Posts a status update to a given incident", "action_configuration": { "action_id": "pagerduty.com:incident-workflows:send-status-update:1", "description": "Posts a status update to a given incident", "inputs": [ { "name": "Message", "parameter_type": "text", "value": "Example status message sent on {{current_date}}" } ], "outputs": [ { "name": "Result", "reference_name": "result", "parameter_type": "text" }, { "name": "Result Summary", "reference_name": "result-summary", "parameter_type": "text" }, { "name": "Error", "reference_name": "error", "parameter_type": "text" } ] } } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/put-incident-workflow # Update an Incident Workflow `PUT https://api.pagerduty.com/incident_workflows/{id}` Update an Incident Workflow An Incident Workflow is a sequence of configurable Steps and associated Triggers that can execute automated Actions for a given Incident. Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow` | object | yes | | | `incident_workflow.id` | string | | Read-only. | | `incident_workflow.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.type` | string | | One of: `incident_workflow`. | | `incident_workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.name` | string | | A descriptive name for the Incident Workflow. | | `incident_workflow.description` | string | | A description of what the Incident Workflow does. | | `incident_workflow.created_at` | string (date-time) | | The timestamp this Incident Workflow was created. Read-only. | | `incident_workflow.team` | object | | If specified then workflow edit permissions will be scoped to members of this team. | | `incident_workflow.team.type` | string | | Type of the referenced object. Read-only. One of: `team_reference`. | | `incident_workflow.team.id` | string | | Unique identifier for the resource. Read-only. | | `incident_workflow.is_enabled` | boolean | | Indicates whether the Incident Workflow is enabled or not. Disabled workflows will not be triggered, and will not count toward the account's enabled workflow limit. Default: `true`. | | `incident_workflow.steps` | array of object | | The ordered list of steps that execute sequentially as part of the workflow. | | `incident_workflow.steps[].id` | string | | Read-only. | | `incident_workflow.steps[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident_workflow.steps[].type` | string | | One of: `step`. | | `incident_workflow.steps[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident_workflow.steps[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident_workflow.steps[].name` | string | yes | A descriptive name for the Step. | | `incident_workflow.steps[].description` | string | | A description of the action performed by the Step. Read-only. | | `incident_workflow.steps[].action_configuration` | object | yes | Configuration of automated action executed by this Step. | | `incident_workflow.steps[].action_configuration.action_id` | string | yes | The identifier of the Action to execute. | | `incident_workflow.steps[].action_configuration.description` | string | | Description of the Action. Read-only. | | `incident_workflow.steps[].action_configuration.inputs` | array of object | yes | An unordered list of standard inputs used to configure the Action to execute. | | `incident_workflow.steps[].action_configuration.inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inputs[].parameter_type` | string | | The data type of this Input. Read-only. | | `incident_workflow.steps[].action_configuration.inputs[].value` | string | yes | The configured value of the Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs` | array of object | | An unordered list of specialized inputs used to configure a workflow-within-a-workflow. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].name` | string | yes | The name for this Input. Input names are unique per action and should be used to find a specific Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value` | object | yes | The configured value of the Inline Steps Input. | | `incident_workflow.steps[].action_configuration.inline_steps_inputs[].value.steps` | array of object | | | | `incident_workflow.steps[].action_configuration.outputs` | array of object | | An unordered list of outputs this action produces. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].name` | string | yes | The name for this Output. Output names are unique per action and should be used to find a specific Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].reference_name` | string | | The reference name of the Output. Read-only. | | `incident_workflow.steps[].action_configuration.outputs[].parameter_type` | string | | The data type produced by this Output. Read-only. | Example: Request Example ```json { "incident_workflow": { "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "steps": [ { "name": "Send Status Update", "action_configuration": { "action_id": "pagerduty.com:incident-workflows:send-status-update:1", "inputs": [ { "name": "Message", "value": "Example status message sent on {{current_date}}" } ] } } ] } } ``` ## Response 200 The changed Incident Workflow ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident_workflow` | object | yes | Same fields as `incident_workflow` above. | Example: Response Example ```json { "incident_workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://pdt-flex-actions.pagerduty.com/flex-workflows/workflows/PSFEVL7", "steps": [ { "id": "P4RG7YW", "type": "step", "name": "Send Status Update", "description": "Posts a status update to a given incident", "action_configuration": { "action_id": "pagerduty.com:incident-workflows:send-status-update:1", "description": "Posts a status update to a given incident", "inputs": [ { "name": "Message", "parameter_type": "text", "value": "Example status message sent on {{current_date}}" } ], "outputs": [ { "name": "Result", "reference_name": "result", "parameter_type": "text" }, { "name": "Result Summary", "reference_name": "result-summary", "parameter_type": "text" }, { "name": "Error", "reference_name": "error", "parameter_type": "text" } ] } } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incident-workflows/update-incident-workflow-trigger # Update a Trigger `PUT https://api.pagerduty.com/incident_workflows/triggers/{id}` Update an existing Incident Workflow Trigger Scoped OAuth requires: `incident_workflows.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. Read-only. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. A previous API version allowed callers to update this property independently. This behavior is deprecated. To update this property set "is_enabled" on the workflow to which this trigger belongs. **Deprecated.** | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | Example: Request Example ```json { "trigger": { "services": [ { "id": "PIJ90N7" } ], "is_subscribed_to_all_services": false, "condition": "incident.priority matches 'P1'" } } ``` ## Response 200 The updated Incident Workflow Trigger ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `trigger` | object | yes | | | `trigger.id` | string | | Read-only. | | `trigger.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `trigger.type` | string | | One of: `workflow_trigger`. | | `trigger.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `trigger.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `trigger.trigger_type_name` | string | | Human readable name for the trigger type. | | `trigger.trigger_type` | string | | One of: `conditional`, `manual`, `incident_type`. | | `trigger.condition` | string | | A PCL condition string. If specified, the trigger will execute when the condition is met on an incident. If unspecified, the trigger will execute on incident creation. Required if trigger_type is “conditional”, not allowed for other trigger types. | | `trigger.trigger_url` | string (url) | | | | `trigger.incident_types` | array of string | | An optional array of Incident Types associated with the trigger when it is of type `incident_type`. | | `trigger.workflow` | object | | Workflow to start when this trigger is invoked. | | `trigger.workflow.id` | string | | | | `trigger.workflow.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `workflow_reference`. | | `trigger.workflow.name` | string | | A descriptive name for the Incident Workflow. | | `trigger.workflow.self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.workflow.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.services` | array of object | | An optional array of Services associated with this workflow. Incidents in any of the listed Services are eligible to fire this Trigger. | | `trigger.services[].id` | string | | | | `trigger.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. | | `trigger.services[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. One of: `service`. | | `trigger.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. | | `trigger.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. | | `trigger.is_subscribed_to_all_services` | boolean | | Indicates that the Trigger should be associated with All Services. | | `trigger.permissions` | object | | An object detailing who can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.restricted` | boolean | | If true, indicates that the Trigger can only be started by authorized Users. If false, any user can start this Trigger. Applicable only to manual Triggers. | | `trigger.permissions.team_id` | string | | The ID of the team whose members can manually start this Trigger. Required and allowed if and only if permissions.restricted is true. | | `trigger.is_disabled` | boolean | | Indicates whether the Trigger is disabled or not. Inherited from the "is_enabled" property on the workflow to which this trigger belongs. This attribute is deprecated, and will be removed in a future version of this API. **Deprecated.** | Example: Response Example ```json { "trigger": { "id": "4ad696eb-bb48-422a-8bd0-6efad6befa29", "type": "workflow_trigger", "trigger_type_name": "Conditional Trigger", "trigger_type": "conditional", "condition": "incident.priority matches 'P1'", "trigger_url": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29/start", "self": "https://api.pagerduty.com/incident_workflows/triggers/4ad696eb-bb48-422a-8bd0-6efad6befa29", "workflow_id": "PSFEVL7", "workflow_name": "Example Incident Workflow", "is_subscribed_to_all_services": false, "services": [ { "id": "PIJ90N7", "summary": "My Application Service", "type": "service", "self": "https://api.pagerduty.com/services/PIJ90N7", "html_url": "https://pdt-circular.pagerduty.com/service-directory/P0544JX" } ], "workflow": { "id": "PSFEVL7", "name": "Example Incident Workflow", "description": "This Incident Workflow is an example", "type": "incident_workflow", "created_at": "2022-12-13T19:55:01.171Z", "self": "https://api.pagerduty.com/incident_workflows/PSFEVL7", "html_url": "https://mydomain.pagerduty.com/flex-workflows/workflows/PSFEVL7" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/cancel-incident-responder-request # Cancel responder requests for an incident `PUT https://api.pagerduty.com/incidents/{id}/responder_requests/cancel` Cancel pending responder requests for the specified incident. This endpoint allows you to cancel responder requests for specified targets that are in a pending state. Only responders who have not yet joined or declined can be cancelled. This endpoint requires the account to have access to the [responder requests](https://support.pagerduty.com/main/docs/add-responders) feature. **Account Ability Requirement**: The account must have the `coordinated_responding` ability. Returns 402 Payment Required if the ability is missing. You can use the [List Abilities API](https://docs.pagerduty.com/developer/api/reference/rest/abilities/list-abilities) to check account abilities. **State Constraints**: Only responders in the `pending` state can be cancelled. Responders who have already `joined` or `declined` are not affected (the result will indicate their current state). **User vs Escalation Policy Behavior**: - **Users**: Direct cancellation, updates state to `user_cancelled`, stops notifications - **Escalation Policies**: Stops the escalation process, updates state of all pending users from that escalation policy to `user_cancelled` and stops notifications **Result Values**: - `cancelled`: Successfully cancelled - `joined`: User already joined (not cancelled) - `declined`: User already declined (not cancelled) - `not_found`: Target not found or not part of any responder request Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `requester_id` | string | yes | The user id of the requester. | | `responder_request_targets` | array of object | yes | The array of targets to cancel. | | `responder_request_targets[].type` | string | yes | The type of target (either a user or an escalation policy) One of: `user_reference`, `escalation_policy_reference`. | | `responder_request_targets[].id` | string | yes | The id of the user or escalation policy. | Example: Request Example ```json { "requester_id": "PL1JMK5", "responder_request_targets": [ { "type": "user_reference", "id": "PJ25ZYX" }, { "type": "escalation_policy_reference", "id": "PEP12AB" } ] } ``` ## Response 200 The result of cancelling responder requests for the given incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `responder_request_targets` | array of object | yes | The array of targets with their cancellation results. | | `responder_request_targets[].type` | string | yes | The type of target (either a user or an escalation policy) One of: `user_reference`, `escalation_policy_reference`. | | `responder_request_targets[].id` | string | yes | The id of the user or escalation policy. | | `responder_request_targets[].result` | string | yes | The result of the cancellation attempt. One of: `cancelled`, `joined`, `declined`, `not_found`. | Example: All Targets Cancelled ```json { "responder_request_targets": [ { "type": "user_reference", "id": "PJ25ZYX", "result": "cancelled" }, { "type": "escalation_policy_reference", "id": "PEP12AB", "result": "cancelled" } ] } ``` Example: Mixed Results ```json { "responder_request_targets": [ { "type": "user_reference", "id": "PJ25ZYX", "result": "cancelled" }, { "type": "user_reference", "id": "PL7A2O4", "result": "joined" }, { "type": "user_reference", "id": "PABC123", "result": "not_found" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident # Create an Incident `POST https://api.pagerduty.com/incidents` 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](https://docs.pagerduty.com/developer/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. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | Details of the incident to be created. | | `incident.type` | string | yes | One of: `incident`. | | `incident.title` | string | yes | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incident.service` | object | yes | | | `incident.service.id` | string | yes | Read-only. | | `incident.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | One of: `service_reference`. | | `incident.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.priority` | object | | | | `incident.priority.id` | string | yes | Read-only. | | `incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.priority.type` | string | yes | One of: `priority_reference`. | | `incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.urgency` | string | | The urgency of the incident. One of: `high`, `low`. | | `incident.body` | object | | | | `incident.body.details` | object | | Additional incident details. | | `incident.incident_key` | string | | A string which identifies the incident. Sending subsequent requests referencing the same service and with the same incident_key will result in those requests being rejected if an open incident matches that incident_key. | | `incident.assignments` | array of object | | Assign the incident to these assignees. Cannot be specified if an escalation policy is given. | | `incident.assignments[].assignee` | object | | | | `incident.assignments[].assignee.id` | string | yes | Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_type` | object | | | | `incident.incident_type.id` | string | | Read-only. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | object | | | | `incident.escalation_policy.id` | string | yes | Read-only. | | `incident.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.conference_bridge` | object | | | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | Example: Request Example ```json { "incident": { "type": "incident", "title": "The server is on fire.", "service": { "id": "PWIXJZS", "type": "service_reference" }, "priority": { "id": "P53ZZH5", "type": "priority_reference" }, "urgency": "high", "incident_key": "baf7cf21b1da41b4b0221008339ff357", "body": { "type": "incident_body", "details": "A disk is getting full on this machine. You should investigate what is causing the disk to fill, and ensure that there is an automated process in place for ensuring data is rotated (eg. logs should have logrotate around them). If data is expected to stay on this disk forever, you should start planning to scale up to a larger disk." }, "incident_type": { "name": "major_incident" }, "escalation_policy": { "id": "PT20YPA", "type": "escalation_policy_reference" } } } ``` ## Response 201 The incident object created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | | | `incident.id` | string | | Read-only. | | `incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incident.service.id` | string | yes | (option 1) Read-only. | | `incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.id` | string | | (option 2) Read-only. | | `incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.name` | string | | (option 2) The name of the service. | | `incident.service.description` | string | | (option 2) The user-provided description of the service. | | `incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incident.service.escalation_policy` | object | yes | (option 2) Same fields as `incident.escalation_policy` above. | | `incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incident.service.teams[].id` | string | yes | Read-only. | | `incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.service.integrations[].id` | string | yes | Read-only. | | `incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.incident_urgency_rule` | object | | (option 2) | | `incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.during_support_hours` | object | | | | `incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incident.service.incident_urgency_rule.during_support_hours` above. | | `incident.service.support_hours` | object | | (option 2) | | `incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incident.service.addons[].id` | string | yes | Read-only. | | `incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.service.addons[].name` | string | | The user entered name of the Addon. | | `incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incident.assignments[].assignee` | one of: object \| object | yes | | | `incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `incident.first_trigger_log_entry.channel.user` | object | | | | `incident.first_trigger_log_entry.channel.team` | object | | | | `incident.first_trigger_log_entry.channel.notification` | object | | | | `incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incident.first_trigger_log_entry.channel.notification.status` | string | | | | `incident.first_trigger_log_entry.channel.notification.` | string | | | | `incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incident.first_trigger_log_entry.agent` | object | | (option 2) | | `incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incident.first_trigger_log_entry.service` | object | | (option 2) Same fields as `incident.service` above. | | `incident.first_trigger_log_entry.incident` | object | | (option 2) | | `incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incident.alert_counts` | object | | | | `incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incident.incident_type` | object | | The incident type of the incident. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.id` | string | | (option 2) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incident.escalation_policy.services[].id` | string | yes | Read-only. | | `incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incident.teams[].id` | string | yes | (option 1) Read-only. | | `incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].id` | string | | (option 2) Read-only. | | `incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incident.pending_actions[].at` | string (date-time) | yes | | | `incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incident.escalation_policy` above. | | `incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incident.alert_grouping.started_at` | string (date-time) | | | | `incident.alert_grouping.ended_at` | string (date-time) | | | | `incident.alert_grouping.alert_grouping_active` | boolean | | | | `incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incident.escalation_policy` above. | | `incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.priority` | object | | | | `incident.priority.id` | string | | Read-only. | | `incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.priority.name` | string | | The user-provided short name of the priority. | | `incident.priority.description` | string | | The user-provided description of the priority. | | `incident.resolve_reason` | object | | | | `incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incident.resolve_reason.incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.incidents_responders[].user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.incidents_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.incidents_responders[].updated_at` | string | | | | `incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `incident.incidents_responders[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.incidents_responders[].requested_at` | string | | | | `incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.responder_requests[].id` | string | | The ID of the responder request. | | `incident.responder_requests[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].requested_at` | string | | The time the request was made. | | `incident.responder_requests[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incident.responder_requests[].responder_request_targets[].summary` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incident.body.details` | object | | Additional incident details. | Example: Response Example ```json { "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" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident-note # Create a note on an incident `POST https://api.pagerduty.com/incidents/{id}/notes` 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `note` | object | yes | | | `note.content` | string | yes | The note content. | Example: Request Example ```json { "note": { "content": "Firefighters are on the scene." } } ``` ## Response 200 The new note. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `note` | object | yes | | | `note.id` | string | | Read-only. | | `note.user` | object | | | | `note.user.id` | string | yes | Read-only. | | `note.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `note.user.type` | string | yes | One of: `user_reference`, `bot_user_reference`. | | `note.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `note.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `note.channel` | object | | The means by which this Note was created. Has different formats depending on type. Read-only. | | `note.channel.summary` | string | yes | A string describing the source of the Note. Read-only. | | `note.channel.id` | string | | Read-only. | | `note.channel.type` | string | | A string that determines the schema of the object. Read-only. | | `note.channel.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `note.channel.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `note.content` | string | yes | The note content. | | `note.created_at` | string (date-time) | | The time at which the note was submitted. Read-only. | | `note.updated_at` | string (date-time) | | The time at which the note was last updated. Read-only. | Example: Response Example ```json { "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" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident-notification-subscribers # Add Notification Subscribers `POST https://api.pagerduty.com/incidents/{id}/status_updates/subscribers` Subscribe the given entities to Incident Status Update Notifications. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to subscribe. | Field | Type | Required | Description | |---|---|---|---| | `subscribers` | array of object | yes | Min items: 1. Items must be unique. | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | Example: Request Example ```json { "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "team" }, { "subscriber_id": "PD1235", "subscriber_type": "team" }, { "subscriber_id": "PD1234", "subscriber_type": "user" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscriptions` | array of object | | | | `subscriptions[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].account_id` | string | | The type of the entity being subscribed to. | | `subscriptions[].result` | string | | The resulting status of the subscription. One of: `success`, `duplicate`, `unauthorized`. | Example: Response Example ```json { "subscriptions": [ { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscriber_id": "PD1234", "subscriber_type": "user", "result": "success" }, { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "duplicate" }, { "account_id": "PD1234", "subscribable_id": "PD1235", "subscribable_type": "incident", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "unauthorized" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident-responder-request # Create a responder request for an incident `POST https://api.pagerduty.com/incidents/{id}/responder_requests` Send a new responder request for the specified incident. This endpoint requires the account to have access to the [responder requests](https://support.pagerduty.com/main/docs/add-responders) feature. **Account Ability Requirement**: The account must have the `coordinated_responding` ability. Returns 402 Payment Required if the ability is missing. You can use the [List Abilities API](https://docs.pagerduty.com/developer/api/reference/rest/abilities/list-abilities) to check account abilities. A user or an escalation policy can be requested. The responder targets will be notified via their high urgency notification rules, until the target user has either accepted or declined the request. Previous responder requests for a given target can be cancelled (preventing them from further notifying or escalating), with the [Cancel Responder Requests](https://docs.pagerduty.com/developer/api/reference/rest/incidents/cancel-incident-responder-request) endpoint. Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `requester_id` | string | yes | The user id of the requester. | | `message` | string | yes | The message sent with the responder request. | | `responder_request_targets` | | yes | The array of targets the responder request is sent to. | Example: Request Example ```json { "requester_id": "PL1JMK5", "message": "Please help with issue - join bridge at +1(234)-567-8910", "responder_request_targets": [ { "responder_request_target": { "id": "PJ25ZYX", "type": "user_reference" } } ] } ``` ## Response 200 The new responder request for the given incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `responder_request` | object | yes | | | `responder_request.id` | string | | The ID of the responder request. | | `responder_request.incident` | object | | | | `responder_request.incident.id` | string | yes | Read-only. | | `responder_request.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `responder_request.incident.type` | string | yes | One of: `incident_reference`. | | `responder_request.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `responder_request.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `responder_request.requester` | object | | | | `responder_request.requester.id` | string | yes | Read-only. | | `responder_request.requester.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `responder_request.requester.type` | string | yes | One of: `user_reference`. | | `responder_request.requester.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `responder_request.requester.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `responder_request.requested_at` | string | | The time the request was made. | | `responder_request.message` | string | | The message sent with the responder request. | | `responder_request.responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `responder_request.responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `responder_request.responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `responder_request.responder_request_targets[].summary` | string | | | | `responder_request.responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `responder_request.responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `responder_request.responder_request_targets[].incident_responders[].user` | object | | Same fields as `responder_request.requester` above. | | `responder_request.responder_request_targets[].incident_responders[].incident` | object | | Same fields as `responder_request.incident` above. | | `responder_request.responder_request_targets[].incident_responders[].updated_at` | string | | | | `responder_request.responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `responder_request.responder_request_targets[].incident_responders[].requester` | object | | Same fields as `responder_request.requester` above. | | `responder_request.responder_request_targets[].incident_responders[].requested_at` | string | | | | `responder_request.responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | Example: Response Example ```json { "responder_request": { "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" } ] } } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident-snooze # Snooze an incident `POST https://api.pagerduty.com/incidents/{id}/snooze` Snooze 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `duration` | integer | yes | The number of seconds to snooze the incident for. After this number of seconds has elapsed, the incident will return to the "triggered" state. Minimum: 1. Maximum: 604800. | Example: Request Example ```json { "duration": 3600 } ``` ## Response 201 The incident that was successfully snoozed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | | | `incident.id` | string | | Read-only. | | `incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incident.service.id` | string | yes | (option 1) Read-only. | | `incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.id` | string | | (option 2) Read-only. | | `incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.name` | string | | (option 2) The name of the service. | | `incident.service.description` | string | | (option 2) The user-provided description of the service. | | `incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incident.service.escalation_policy` | object | yes | (option 2) | | `incident.service.escalation_policy.id` | string | yes | Read-only. | | `incident.service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incident.service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incident.service.teams[].id` | string | yes | Read-only. | | `incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.service.integrations[].id` | string | yes | Read-only. | | `incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.incident_urgency_rule` | object | | (option 2) | | `incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.during_support_hours` | object | | | | `incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incident.service.incident_urgency_rule.during_support_hours` above. | | `incident.service.support_hours` | object | | (option 2) | | `incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incident.service.addons[].id` | string | yes | Read-only. | | `incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.service.addons[].name` | string | | The user entered name of the Addon. | | `incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incident.assignments[].assignee` | one of: object \| object | yes | | | `incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `incident.first_trigger_log_entry.channel.user` | object | | | | `incident.first_trigger_log_entry.channel.team` | object | | | | `incident.first_trigger_log_entry.channel.notification` | object | | | | `incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user` | object | | | | `incident.first_trigger_log_entry.channel.notification.user.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `incident.first_trigger_log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incident.first_trigger_log_entry.channel.notification.status` | string | | | | `incident.first_trigger_log_entry.channel.notification.` | string | | | | `incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incident.first_trigger_log_entry.agent` | object | | (option 2) | | `incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incident.first_trigger_log_entry.service` | object | | (option 2) | | `incident.first_trigger_log_entry.service.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `incident.first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.incident` | object | | (option 2) | | `incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incident.alert_counts` | object | | | | `incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incident.incident_type` | object | | The incident type of the incident. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.id` | string | | (option 2) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incident.escalation_policy.services[].id` | string | yes | Read-only. | | `incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incident.teams[].id` | string | yes | (option 1) Read-only. | | `incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].id` | string | | (option 2) Read-only. | | `incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incident.pending_actions[].at` | string (date-time) | yes | | | `incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incident.service.escalation_policy` above. | | `incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incident.alert_grouping.started_at` | string (date-time) | | | | `incident.alert_grouping.ended_at` | string (date-time) | | | | `incident.alert_grouping.alert_grouping_active` | boolean | | | | `incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incident.service.escalation_policy` above. | | `incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.priority` | object | | | | `incident.priority.id` | string | | Read-only. | | `incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.priority.name` | string | | The user-provided short name of the priority. | | `incident.priority.description` | string | | The user-provided description of the priority. | | `incident.resolve_reason` | object | | | | `incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incident.resolve_reason.incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.incidents_responders[].user` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.incidents_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.incidents_responders[].updated_at` | string | | | | `incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `incident.incidents_responders[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.incidents_responders[].requested_at` | string | | | | `incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.responder_requests[].id` | string | | The ID of the responder request. | | `incident.responder_requests[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].requested_at` | string | | The time the request was made. | | `incident.responder_requests[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incident.responder_requests[].responder_request_targets[].summary` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incident.body.details` | object | | Additional incident details. | Example: Response Example ```json { "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", "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": "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" } ], "urgency": "high" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/create-incident-status-update # Create a status update on an incident `POST https://api.pagerduty.com/incidents/{id}/status_updates` Create a new status update for the specified incident. Optionally pass `subject` and `html_message` properties in the request body to override the email notification that gets sent. An incident represents a problem or an issue that needs to be addressed and resolved. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `message` | string | yes | The message to be posted as a status update. | | `subject` | string | | The subject to be sent for the custom html email status update. Required if sending custom html email. | | `html_message` | string | | The html content to be sent for the custom html email status update. Required if sending custom html email. | Example: Request Example ```json { "message": "The server fire is spreading.", "subject": "Server Fire Update", "html_message": "

Server is still on fire

" } ``` ## Response 200 The new status update for the specified incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status_update` | object | yes | | | `status_update.id` | string | | | | `status_update.message` | string | | The message of the status update. | | `status_update.created_at` | string | | The date/time when this status update was created. | | `status_update.sender` | object | | | | `status_update.sender.id` | string | yes | Read-only. | | `status_update.sender.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `status_update.sender.type` | string | yes | One of: `user_reference`. | | `status_update.sender.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `status_update.sender.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `status_update.subject` | string | | The subject of the custom html email status update. Present if included in request body. | | `status_update.html_message` | string | | The html content of the custom html email status update. Present if included in request body. | Example: Response Example ```json { "status_update": { "id": "PWL7QXS", "message": "The server fire is spreading.", "sender": { "id": "PXPGF42", "type": "user_reference", "summary": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" }, "created_at": "2013-03-06T15:28:51-05:00", "html_message": "

Server is still on fire

", "subject": "Server Fire Update" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/delete-incident-note # Delete a note on an incident `DELETE https://api.pagerduty.com/incidents/{id}/notes/{note_id}` Delete an existing note 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `note_id` | string | yes | The id of the note. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Note deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident # Get an incident `GET https://api.pagerduty.com/incidents/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `acknowledgers`, `agents`, `assignees`, `conference_bridge`, `custom_fields`, `escalation_policies`, `first_trigger_log_entries`, `priorities`, `services`, `teams`, `users`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The incident requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | | | `incident.id` | string | | Read-only. | | `incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incident.service.id` | string | yes | (option 1) Read-only. | | `incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.id` | string | | (option 2) Read-only. | | `incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.name` | string | | (option 2) The name of the service. | | `incident.service.description` | string | | (option 2) The user-provided description of the service. | | `incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incident.service.escalation_policy` | object | yes | (option 2) | | `incident.service.escalation_policy.id` | string | yes | Read-only. | | `incident.service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incident.service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incident.service.teams[].id` | string | yes | Read-only. | | `incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.service.integrations[].id` | string | yes | Read-only. | | `incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.incident_urgency_rule` | object | | (option 2) | | `incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.during_support_hours` | object | | | | `incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incident.service.incident_urgency_rule.during_support_hours` above. | | `incident.service.support_hours` | object | | (option 2) | | `incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incident.service.addons[].id` | string | yes | Read-only. | | `incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.service.addons[].name` | string | | The user entered name of the Addon. | | `incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incident.assignments[].assignee` | one of: object \| object | yes | | | `incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `incident.first_trigger_log_entry.channel.user` | object | | | | `incident.first_trigger_log_entry.channel.team` | object | | | | `incident.first_trigger_log_entry.channel.notification` | object | | | | `incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user` | object | | | | `incident.first_trigger_log_entry.channel.notification.user.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `incident.first_trigger_log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incident.first_trigger_log_entry.channel.notification.status` | string | | | | `incident.first_trigger_log_entry.channel.notification.` | string | | | | `incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incident.first_trigger_log_entry.agent` | object | | (option 2) | | `incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incident.first_trigger_log_entry.service` | object | | (option 2) | | `incident.first_trigger_log_entry.service.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `incident.first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.incident` | object | | (option 2) | | `incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incident.alert_counts` | object | | | | `incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incident.incident_type` | object | | The incident type of the incident. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.id` | string | | (option 2) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incident.escalation_policy.services[].id` | string | yes | Read-only. | | `incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incident.teams[].id` | string | yes | (option 1) Read-only. | | `incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].id` | string | | (option 2) Read-only. | | `incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incident.pending_actions[].at` | string (date-time) | yes | | | `incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incident.service.escalation_policy` above. | | `incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incident.alert_grouping.started_at` | string (date-time) | | | | `incident.alert_grouping.ended_at` | string (date-time) | | | | `incident.alert_grouping.alert_grouping_active` | boolean | | | | `incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incident.service.escalation_policy` above. | | `incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.priority` | object | | | | `incident.priority.id` | string | | Read-only. | | `incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.priority.name` | string | | The user-provided short name of the priority. | | `incident.priority.description` | string | | The user-provided description of the priority. | | `incident.resolve_reason` | object | | | | `incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incident.resolve_reason.incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.incidents_responders[].user` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.incidents_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.incidents_responders[].updated_at` | string | | | | `incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `incident.incidents_responders[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.incidents_responders[].requested_at` | string | | | | `incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.responder_requests[].id` | string | | The ID of the responder request. | | `incident.responder_requests[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].requested_at` | string | | The time the request was made. | | `incident.responder_requests[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incident.responder_requests[].responder_request_targets[].summary` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incident.first_trigger_log_entry.channel.notification.user` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incident.body.details` | object | | Additional incident details. | Example: Response Example ```json { "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" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident-alert # Get an alert `GET https://api.pagerduty.com/incidents/{id}/alerts/{alert_id}` Show detailed information about an alert. Accepts an alert id. An incident represents a problem or an issue that needs to be addressed and resolved. When a service sends an event to PagerDuty, an alert and corresponding incident is triggered in PagerDuty. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `alert_id` | string | yes | The id of the alert to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The alert requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert` | object | yes | | | `alert.id` | string | | Read-only. | | `alert.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.type` | string | yes | The type of object being created. One of: `alert`. Default: `alert`. | | `alert.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.created_at` | string (date-time) | | The date/time the alert was first triggered. Read-only. | | `alert.status` | string | | The current status of the alert. One of: `triggered`, `resolved`. | | `alert.alert_key` | string | | The alert's de-duplication key. Read-only. | | `alert.service` | object | | | | `alert.service.id` | string | yes | Read-only. | | `alert.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.service.type` | string | yes | One of: `service_reference`. | | `alert.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.first_trigger_log_entry` | object | | | | `alert.first_trigger_log_entry.id` | string | yes | Read-only. | | `alert.first_trigger_log_entry.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.first_trigger_log_entry.type` | string | yes | One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `alert.first_trigger_log_entry.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.first_trigger_log_entry.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.incident` | object | | | | `alert.incident.id` | string | yes | Read-only. | | `alert.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.incident.type` | string | yes | One of: `incident_reference`. | | `alert.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.suppressed` | boolean | | Whether or not an alert is suppressed. Suppressed alerts are not created with a parent incident. Read-only. Default: `false`. | | `alert.severity` | string | | The magnitude of the problem as reported by the monitoring tool. Read-only. One of: `info`, `warning`, `error`, `critical`. | | `alert.integration` | object | | | | `alert.integration.id` | string | yes | Read-only. | | `alert.integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `alert.integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.body` | object | | A JSON object containing data describing the alert. Read-only. | | `alert.body.type` | string | | The type of the body. One of: `alert_body`. | | `alert.body.contexts` | array of object | | Contexts to be included with the body such as links to graphs or images. Read-only. | | `alert.body.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `alert.body.contexts[].href` | string | | The link's target url. | | `alert.body.contexts[].src` | string | | The image's source url. | | `alert.body.contexts[].text` | string | | The alternate display for an image. | | `alert.body.details` | object | | An arbitrary JSON object or string containing any data explaining the nature of the alert. Read-only. | Example: Response Example ```json { "alert": { "id": "PT4KHLK", "type": "alert", "summary": "The server is on fire.", "self": "https://api.pagerduty.com/incident/PT4KHLX/alerts/PT4KHLK", "html_url": "https://subdomain.pagerduty.com/alerts/PT4KHLK", "created_at": "2015-10-06T21:30:42Z", "status": "resolved", "alert_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" }, "incident": { "id": "PT4KHLX", "type": "incident_reference", "summary": "[#1234] The server is on fire.", "self": "https://api.pagerduty.com/incidents/PT4KHLX", "html_url": "https://subdomain.pagerduty.com/incidents/PT4KHLX" }, "suppressed": false, "severity": "critical", "integration": { "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" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident-field-values # Get Custom Field Values `GET https://api.pagerduty.com/incidents/{id}/custom_fields/values` Get custom field values for an incident. Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Response 200 The list of custom field values. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of object | yes | | | `custom_fields[].id` | string | yes | Id of the field. | | `custom_fields[].name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].type` | string | yes | Determines the type of the reference. One of: `field_value`. | | `custom_fields[].display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `custom_fields[].field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `custom_fields[].data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `custom_fields[].description` | string \| null | yes | A description of the data this field contains. Max length: 1000. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | yes | | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Response Example ```json { "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" } ] } ``` Example: Response Example ```json { "custom_fields": [ { "id": "PT4KHEE", "type": "field_value", "name": "environment", "display_name": "Runtime Environment", "description": "environment where incident occurred", "data_type": "string", "field_type": "multi_value_fixed", "value": [ "production", "staging" ] } ] } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident-impacted-business-services # List Business Services impacted by the given Incident `GET https://api.pagerduty.com/incidents/{id}/business_services/impacts` Retrieve a list of Business Services that are being impacted by the given Incident. Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | | `services` | array of object | | | | `services[].id` | string | | Read-only. | | `services[].name` | string | | Read-only. | | `services[].type` | string | | The kind of object that has been impacted. One of: `business_service`. | | `services[].status` | string | | The current impact status of the object. One of: `impacted`, `not_impacted`. | | `services[].additional_fields` | object | | | | `services[].additional_fields.highest_impacting_priority` | object \| null | | Priority information for the highest priority level that is affecting the impacted object. | | `services[].additional_fields.highest_impacting_priority.id` | string | | Read-only. | | `services[].additional_fields.highest_impacting_priority.order` | integer | | Read-only. | Example: Response Example ```json { "limit": 100, "next_cursor": null, "services": [ { "id": "PD1234", "name": "Web API", "type": "business_service", "status": "impacted" }, { "id": "PF9KMXH", "name": "Analytics Backend", "type": "business_service", "status": "impacted" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident-notification-subscribers # List Notification Subscribers `GET https://api.pagerduty.com/incidents/{id}/status_updates/subscribers` Retrieve a list of Notification Subscribers on the Incident. > Users must be added through `POST /incident/{id}/status_updates/subscribers` to be returned from this endpoint. Scoped OAuth requires: `subscribers.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `subscribers` | array of object | | | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscribers[].has_indirect_subscription` | boolean | | If this subcriber has an indirect subscription to this incident via another object. | | `subscribers[].subscribed_via` | array \| null | | | | `account_id` | string | | The ID of the account belonging to the subscriber entity. | Example: Response Example ```json { "limit": 100, "more": false, "offset": 0, "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "user", "has_indirect_subscription": false, "subscribed_via": null }, { "subscriber_id": "PD1234", "subscriber_type": "team", "has_indirect_subscription": true, "subscribed_via": [ { "id": "PD1234", "type": "business_service" } ] } ], "account_id": "PD1234", "total": 2 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-incident-scribe-transcripts # Get Scribe transcripts for an incident `GET https://api.pagerduty.com/incidents/{id}/scribe_transcripts` Get download links for the Scribe transcripts of the specified incident. Only Scribes that have completed are returned; a Scribe that is still in progress does not appear in the response. Each entry contains a presigned `download_url` for a single transcript format, selected with the `format` query parameter (`enhanced` by default, or `raw`). The `download_url` is time-limited and expires after one hour, so request a new one if it has expired. `download_url` is `null` when the transcript is not available for the requested format. Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `format` | string | | The transcript format to return a download link for. One of: `enhanced`, `raw`. Default: `enhanced`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The completed Scribe transcripts for the specified incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `scribe_transcripts` | array of object | yes | The Scribe transcripts associated with the incident. | | `scribe_transcripts[].scribe_id` | string | yes | The ID of the Scribe. | | `scribe_transcripts[].format` | string | yes | The transcript format that `download_url` corresponds to. One of: `enhanced`, `raw`. | | `scribe_transcripts[].started_at` | string (date-time) | | The time the Scribe started. | | `scribe_transcripts[].ended_at` | string \| null (date-time) | | The time the Scribe ended. | | `scribe_transcripts[].download_url` | string \| null | yes | A presigned URL to download the transcript. Expires after one hour. `null` if the transcript is not available. | Example: Response Example ```json { "scribe_transcripts": [ { "format": "enhanced", "started_at": "2026-09-28T09:22:57.896Z", "scribe_id": "AGQOOUXTMR3TPA3ULKC7KHPZCQ", "ended_at": "2026-09-28T09:24:50.097Z", "download_url": "https://s3.us-west-2.amazonaws.com/example-bucket/AGQOOUXTMR3TPA3ULKC7KHPZCQ_enhanced_transcript.json?X-Amz-Expires=3600&X-Amz-Signature=EXAMPLE" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-outlier-incident # Get Outlier Incident `GET https://api.pagerduty.com/incidents/{id}/outlier_incident` Gets Outlier Incident information for a given Incident on its Service. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#outlier-incident) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search. | | `additional_details[]` | string | | Array of additional attributes to any of the returned incidents for related incidents. One of: `incident`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Outlier Incident information calculated over the same Service as the given Incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `outlier_incident` | object | | Outlier Incident information calculated over the same Service as the given Incident. | | `outlier_incident.incident` | object | | | | `outlier_incident.incident.id` | string | | Read-only. | | `outlier_incident.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `outlier_incident.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `outlier_incident.incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `outlier_incident.incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `outlier_incident.incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `outlier_incident.incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `outlier_incident.incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `outlier_incident.incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `outlier_incident.incident.service.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `outlier_incident.incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `outlier_incident.incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.name` | string | | (option 2) The name of the service. | | `outlier_incident.incident.service.description` | string | | (option 2) The user-provided description of the service. | | `outlier_incident.incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `outlier_incident.incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `outlier_incident.incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `outlier_incident.incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `outlier_incident.incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `outlier_incident.incident.service.escalation_policy` | object | yes | (option 2) | | `outlier_incident.incident.service.escalation_policy.id` | string | yes | Read-only. | | `outlier_incident.incident.service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `outlier_incident.incident.service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `outlier_incident.incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `outlier_incident.incident.service.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `outlier_incident.incident.service.integrations[].id` | string | yes | Read-only. | | `outlier_incident.incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `outlier_incident.incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.incident_urgency_rule` | object | | (option 2) | | `outlier_incident.incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `outlier_incident.incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `outlier_incident.incident.service.incident_urgency_rule.during_support_hours` | object | | | | `outlier_incident.incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `outlier_incident.incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `outlier_incident.incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `outlier_incident.incident.service.incident_urgency_rule.during_support_hours` above. | | `outlier_incident.incident.service.support_hours` | object | | (option 2) | | `outlier_incident.incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `outlier_incident.incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `outlier_incident.incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `outlier_incident.incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `outlier_incident.incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `outlier_incident.incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `outlier_incident.incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `outlier_incident.incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `outlier_incident.incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `outlier_incident.incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `outlier_incident.incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `outlier_incident.incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `outlier_incident.incident.service.addons[].id` | string | yes | Read-only. | | `outlier_incident.incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `outlier_incident.incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `outlier_incident.incident.service.addons[].name` | string | | The user entered name of the Addon. | | `outlier_incident.incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `outlier_incident.incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `outlier_incident.incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `outlier_incident.incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `outlier_incident.incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `outlier_incident.incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `outlier_incident.incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `outlier_incident.incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `outlier_incident.incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `outlier_incident.incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `outlier_incident.incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `outlier_incident.incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `outlier_incident.incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `outlier_incident.incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `outlier_incident.incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `outlier_incident.incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `outlier_incident.incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `outlier_incident.incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `outlier_incident.incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `outlier_incident.incident.assignments[].assignee` | one of: object \| object | yes | | | `outlier_incident.incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `outlier_incident.incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `outlier_incident.incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `outlier_incident.incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `outlier_incident.incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `outlier_incident.incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `outlier_incident.incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `outlier_incident.incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `outlier_incident.incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `outlier_incident.incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `outlier_incident.incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `outlier_incident.incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `outlier_incident.incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `outlier_incident.incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `outlier_incident.incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `outlier_incident.incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `outlier_incident.incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `outlier_incident.incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `outlier_incident.incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `outlier_incident.incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `outlier_incident.incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `outlier_incident.incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `outlier_incident.incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `outlier_incident.incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `outlier_incident.incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `outlier_incident.incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `outlier_incident.incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `outlier_incident.incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `outlier_incident.incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `outlier_incident.incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `outlier_incident.incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `outlier_incident.incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `outlier_incident.incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `outlier_incident.incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `outlier_incident.incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `outlier_incident.incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `outlier_incident.incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `outlier_incident.incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `outlier_incident.incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `outlier_incident.incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `outlier_incident.incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `outlier_incident.incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `outlier_incident.incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `outlier_incident.incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `outlier_incident.incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `outlier_incident.incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `outlier_incident.incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `outlier_incident.incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `outlier_incident.incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `outlier_incident.incident.first_trigger_log_entry.channel.user` | object | | | | `outlier_incident.incident.first_trigger_log_entry.channel.team` | object | | | | `outlier_incident.incident.first_trigger_log_entry.channel.notification` | object | | | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` | object | | | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user.id` | string | yes | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.status` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.notification.` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `outlier_incident.incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `outlier_incident.incident.first_trigger_log_entry.agent` | object | | (option 2) | | `outlier_incident.incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `outlier_incident.incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `outlier_incident.incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `outlier_incident.incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `outlier_incident.incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `outlier_incident.incident.first_trigger_log_entry.service` | object | | (option 2) | | `outlier_incident.incident.first_trigger_log_entry.service.id` | string | yes | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `outlier_incident.incident.first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.incident` | object | | (option 2) | | `outlier_incident.incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `outlier_incident.incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `outlier_incident.incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `outlier_incident.incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `outlier_incident.incident.alert_counts` | object | | | | `outlier_incident.incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `outlier_incident.incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `outlier_incident.incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `outlier_incident.incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `outlier_incident.incident.incident_type` | object | | The incident type of the incident. | | `outlier_incident.incident.incident_type.name` | string | | The name of the Incident Type. | | `outlier_incident.incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `outlier_incident.incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `outlier_incident.incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.escalation_policy.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `outlier_incident.incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `outlier_incident.incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `outlier_incident.incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `outlier_incident.incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `outlier_incident.incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `outlier_incident.incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `outlier_incident.incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `outlier_incident.incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `outlier_incident.incident.escalation_policy.services[].id` | string | yes | Read-only. | | `outlier_incident.incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `outlier_incident.incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `outlier_incident.incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `outlier_incident.incident.teams[].id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `outlier_incident.incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.teams[].id` | string | | (option 2) Read-only. | | `outlier_incident.incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `outlier_incident.incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `outlier_incident.incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `outlier_incident.incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `outlier_incident.incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `outlier_incident.incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `outlier_incident.incident.pending_actions[].at` | string (date-time) | yes | | | `outlier_incident.incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `outlier_incident.incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `outlier_incident.incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `outlier_incident.incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `outlier_incident.incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `outlier_incident.incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `outlier_incident.incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `outlier_incident.incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `outlier_incident.incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `outlier_incident.incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `outlier_incident.incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `outlier_incident.incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `outlier_incident.incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `outlier_incident.incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `outlier_incident.incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `outlier_incident.incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `outlier_incident.incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `outlier_incident.incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `outlier_incident.incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `outlier_incident.incident.service.escalation_policy` above. | | `outlier_incident.incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `outlier_incident.incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `outlier_incident.incident.service.incident_urgency_rule` above. | | `outlier_incident.incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `outlier_incident.incident.service.support_hours` above. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `outlier_incident.incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `outlier_incident.incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `outlier_incident.incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `outlier_incident.incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `outlier_incident.incident.service.auto_pause_notifications_parameters` above. | | `outlier_incident.incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `outlier_incident.incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `outlier_incident.incident.alert_grouping.started_at` | string (date-time) | | | | `outlier_incident.incident.alert_grouping.ended_at` | string (date-time) | | | | `outlier_incident.incident.alert_grouping.alert_grouping_active` | boolean | | | | `outlier_incident.incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `outlier_incident.incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `outlier_incident.incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `outlier_incident.incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `outlier_incident.incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `outlier_incident.incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `outlier_incident.incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `outlier_incident.incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `outlier_incident.incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `outlier_incident.incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `outlier_incident.incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `outlier_incident.incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `outlier_incident.incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `outlier_incident.incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `outlier_incident.incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `outlier_incident.incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `outlier_incident.incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `outlier_incident.incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `outlier_incident.incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `outlier_incident.incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `outlier_incident.incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `outlier_incident.incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `outlier_incident.incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `outlier_incident.incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `outlier_incident.incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `outlier_incident.incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `outlier_incident.incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `outlier_incident.incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `outlier_incident.incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `outlier_incident.incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `outlier_incident.incident.service.escalation_policy` above. | | `outlier_incident.incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `outlier_incident.incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `outlier_incident.incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `outlier_incident.incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `outlier_incident.incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `outlier_incident.incident.service.incident_urgency_rule` above. | | `outlier_incident.incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `outlier_incident.incident.service.support_hours` above. | | `outlier_incident.incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `outlier_incident.incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `outlier_incident.incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `outlier_incident.incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `outlier_incident.incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `outlier_incident.incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `outlier_incident.incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `outlier_incident.incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `outlier_incident.incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `outlier_incident.incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `outlier_incident.incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `outlier_incident.incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `outlier_incident.incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `outlier_incident.incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `outlier_incident.incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `outlier_incident.incident.service.auto_pause_notifications_parameters` above. | | `outlier_incident.incident.priority` | object | | | | `outlier_incident.incident.priority.id` | string | | Read-only. | | `outlier_incident.incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `outlier_incident.incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `outlier_incident.incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `outlier_incident.incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `outlier_incident.incident.priority.name` | string | | The user-provided short name of the priority. | | `outlier_incident.incident.priority.description` | string | | The user-provided description of the priority. | | `outlier_incident.incident.resolve_reason` | object | | | | `outlier_incident.incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `outlier_incident.incident.resolve_reason.incident` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.incident` above. | | `outlier_incident.incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `outlier_incident.incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `outlier_incident.incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `outlier_incident.incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `outlier_incident.incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `outlier_incident.incident.incidents_responders[].user` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` above. | | `outlier_incident.incident.incidents_responders[].incident` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.incident` above. | | `outlier_incident.incident.incidents_responders[].updated_at` | string | | | | `outlier_incident.incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `outlier_incident.incident.incidents_responders[].requester` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` above. | | `outlier_incident.incident.incidents_responders[].requested_at` | string | | | | `outlier_incident.incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `outlier_incident.incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `outlier_incident.incident.responder_requests[].id` | string | | The ID of the responder request. | | `outlier_incident.incident.responder_requests[].incident` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.incident` above. | | `outlier_incident.incident.responder_requests[].requester` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` above. | | `outlier_incident.incident.responder_requests[].requested_at` | string | | The time the request was made. | | `outlier_incident.incident.responder_requests[].message` | string | | The message sent with the responder request. | | `outlier_incident.incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `outlier_incident.incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].summary` | string | | | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` above. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.incident` above. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `outlier_incident.incident.first_trigger_log_entry.channel.notification.user` above. | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `outlier_incident.incident.responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `outlier_incident.incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `outlier_incident.incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `outlier_incident.incident.body.details` | object | | Additional incident details. | | `outlier_incident.incident_template` | object | | | | `outlier_incident.incident_template.id` | string | | Read-only. | | `outlier_incident.incident_template.cluster_id` | string | | The cluster the Incident Template pattern belongs to. Read-only. | | `outlier_incident.incident_template.mined_text` | string | | The Incident Template mined pattern text. Read-only. | Example: Response Example ```json { "outlier_incident": { "incident": { "id": "PR2P3RW", "created_at": "2020-11-18T13:08:14Z", "self": "https://api.pagerduty.com/incidents/PR2P3RW", "title": "[LINUX]Used disk space is more than 5 GB on volume /var/log : PROBLEM for ce51323", "occurrence": { "count": 10, "frequency": 0.04, "category": "rare", "since": "2020-09-23T13:08:14Z", "until": "2021-01-18T13:08:14Z" } }, "incident_template": { "id": "PX3P1PX", "cluster_id": "P2B3X5", "mined_text": "[LINUX]Used disk space is more than on volume <*> : PROBLEM for <*>" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-past-incidents # Get Past Incidents `GET https://api.pagerduty.com/incidents/{id}/past_incidents` Past Incidents returns Incidents within the past 6 months that have similar metadata and were generated on the same Service as the parent Incident. By default, 5 Past Incidents are returned. Note: This feature is currently available as part of the Event Intelligence package or Digital Operations plan only. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#past_incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results to be returned in the response. Default: `5`. Minimum: 1. Maximum: 999. | | `total` | boolean | | By default the `total` field in the response body is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated with the total number of Past Incidents. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `past_incidents` | array of object | | Aggregate of past incidents. | | `past_incidents[].incident` | object | | Incident model reference. | | `past_incidents[].incident.id` | string | | The globally unique identifier of the incident. | | `past_incidents[].incident.created_at` | string | | The date/time the incident was first triggered. | | `past_incidents[].incident.self` | string | | The URL at which the object is accessible. | | `past_incidents[].incident.title` | string | | The description of the nature, symptoms, cause, or effect of the incident. | | `past_incidents[].score` | number | | The computed similarity score associated with the incident and parent incident. | | `total` | number | | The total number of Past Incidents if the total parameter was set in the request. | | `limit` | number | | The maximum number of Incidents requested. | Example: Response Example ```json { "past_incidents": [ { "incident": { "id": "PFBE9I2", "created_at": "2020-11-04T16:08:15Z", "self": "https://api.pagerduty.com/incidents/PFBE9I2", "title": "Things are so broken!" }, "score": 46.8249 }, { "incident": { "id": "P1J6V6M", "created_at": "2020-10-22T17:18:14Z", "self": "https://api.pagerduty.com/incidents/P1J6V6M", "title": "Things are so broken!" }, "score": 46.8249 }, { "incident": { "id": "P6HPX5N", "created_at": "2020-10-06T22:01:13Z", "self": "https://api.pagerduty.com/incidents/P6HPX5N", "title": "You forgot to feed the cat!" }, "score": 0 } ], "total": 3, "limit": 5 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/get-related-incidents # Get Related Incidents `GET https://api.pagerduty.com/incidents/{id}/related_incidents` Returns the 20 most recent Related Incidents that are impacting other Responders and Services. Note: This feature is currently available as part of the Event Intelligence package or Digital Operations plan only. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#related_incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `additional_details[]` | string | | Array of additional attributes to any of the returned incidents for related incidents. One of: `incident`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of Related Incidents and their relationships. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `related_incidents` | array of object | | A list of Related Incidents and their relationships. | | `related_incidents[].incident` | object | | | | `related_incidents[].incident.id` | string | | Read-only. | | `related_incidents[].incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `related_incidents[].incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `related_incidents[].incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `related_incidents[].incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `related_incidents[].incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `related_incidents[].incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `related_incidents[].incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `related_incidents[].incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `related_incidents[].incident.service.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `related_incidents[].incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `related_incidents[].incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.name` | string | | (option 2) The name of the service. | | `related_incidents[].incident.service.description` | string | | (option 2) The user-provided description of the service. | | `related_incidents[].incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `related_incidents[].incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `related_incidents[].incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `related_incidents[].incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `related_incidents[].incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `related_incidents[].incident.service.escalation_policy` | object | yes | (option 2) | | `related_incidents[].incident.service.escalation_policy.id` | string | yes | Read-only. | | `related_incidents[].incident.service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `related_incidents[].incident.service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `related_incidents[].incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `related_incidents[].incident.service.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `related_incidents[].incident.service.integrations[].id` | string | yes | Read-only. | | `related_incidents[].incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `related_incidents[].incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.incident_urgency_rule` | object | | (option 2) | | `related_incidents[].incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `related_incidents[].incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `related_incidents[].incident.service.incident_urgency_rule.during_support_hours` | object | | | | `related_incidents[].incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `related_incidents[].incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `related_incidents[].incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `related_incidents[].incident.service.incident_urgency_rule.during_support_hours` above. | | `related_incidents[].incident.service.support_hours` | object | | (option 2) | | `related_incidents[].incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `related_incidents[].incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `related_incidents[].incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `related_incidents[].incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `related_incidents[].incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `related_incidents[].incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `related_incidents[].incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `related_incidents[].incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `related_incidents[].incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `related_incidents[].incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `related_incidents[].incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `related_incidents[].incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `related_incidents[].incident.service.addons[].id` | string | yes | Read-only. | | `related_incidents[].incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `related_incidents[].incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `related_incidents[].incident.service.addons[].name` | string | | The user entered name of the Addon. | | `related_incidents[].incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `related_incidents[].incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `related_incidents[].incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `related_incidents[].incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `related_incidents[].incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `related_incidents[].incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `related_incidents[].incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `related_incidents[].incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `related_incidents[].incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `related_incidents[].incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `related_incidents[].incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `related_incidents[].incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `related_incidents[].incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `related_incidents[].incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `related_incidents[].incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `related_incidents[].incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `related_incidents[].incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `related_incidents[].incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `related_incidents[].incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `related_incidents[].incident.assignments[].assignee` | one of: object \| object | yes | | | `related_incidents[].incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `related_incidents[].incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `related_incidents[].incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `related_incidents[].incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `related_incidents[].incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `related_incidents[].incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `related_incidents[].incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `related_incidents[].incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `related_incidents[].incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `related_incidents[].incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `related_incidents[].incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `related_incidents[].incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `related_incidents[].incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `related_incidents[].incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `related_incidents[].incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `related_incidents[].incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `related_incidents[].incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `related_incidents[].incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `related_incidents[].incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `related_incidents[].incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `related_incidents[].incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `related_incidents[].incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `related_incidents[].incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `related_incidents[].incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `related_incidents[].incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `related_incidents[].incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `related_incidents[].incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `related_incidents[].incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `related_incidents[].incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `related_incidents[].incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `related_incidents[].incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `related_incidents[].incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `related_incidents[].incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `related_incidents[].incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `related_incidents[].incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `related_incidents[].incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `related_incidents[].incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `related_incidents[].incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `related_incidents[].incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `related_incidents[].incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `related_incidents[].incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `related_incidents[].incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `related_incidents[].incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `related_incidents[].incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `related_incidents[].incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `related_incidents[].incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `related_incidents[].incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `related_incidents[].incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `related_incidents[].incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `related_incidents[].incident.first_trigger_log_entry.channel.user` | object | | | | `related_incidents[].incident.first_trigger_log_entry.channel.team` | object | | | | `related_incidents[].incident.first_trigger_log_entry.channel.notification` | object | | | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user` | object | | | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user.id` | string | yes | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.status` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.notification.` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `related_incidents[].incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `related_incidents[].incident.first_trigger_log_entry.agent` | object | | (option 2) | | `related_incidents[].incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `related_incidents[].incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `related_incidents[].incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `related_incidents[].incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `related_incidents[].incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `related_incidents[].incident.first_trigger_log_entry.service` | object | | (option 2) | | `related_incidents[].incident.first_trigger_log_entry.service.id` | string | yes | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `related_incidents[].incident.first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.incident` | object | | (option 2) | | `related_incidents[].incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `related_incidents[].incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `related_incidents[].incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `related_incidents[].incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `related_incidents[].incident.alert_counts` | object | | | | `related_incidents[].incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `related_incidents[].incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `related_incidents[].incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `related_incidents[].incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `related_incidents[].incident.incident_type` | object | | The incident type of the incident. | | `related_incidents[].incident.incident_type.name` | string | | The name of the Incident Type. | | `related_incidents[].incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `related_incidents[].incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `related_incidents[].incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.escalation_policy.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `related_incidents[].incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `related_incidents[].incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `related_incidents[].incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `related_incidents[].incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `related_incidents[].incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `related_incidents[].incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `related_incidents[].incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `related_incidents[].incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `related_incidents[].incident.escalation_policy.services[].id` | string | yes | Read-only. | | `related_incidents[].incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `related_incidents[].incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `related_incidents[].incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `related_incidents[].incident.teams[].id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `related_incidents[].incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.teams[].id` | string | | (option 2) Read-only. | | `related_incidents[].incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `related_incidents[].incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `related_incidents[].incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `related_incidents[].incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `related_incidents[].incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `related_incidents[].incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `related_incidents[].incident.pending_actions[].at` | string (date-time) | yes | | | `related_incidents[].incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `related_incidents[].incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `related_incidents[].incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `related_incidents[].incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `related_incidents[].incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `related_incidents[].incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `related_incidents[].incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `related_incidents[].incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `related_incidents[].incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `related_incidents[].incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `related_incidents[].incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `related_incidents[].incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `related_incidents[].incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `related_incidents[].incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `related_incidents[].incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `related_incidents[].incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `related_incidents[].incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `related_incidents[].incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `related_incidents[].incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `related_incidents[].incident.service.escalation_policy` above. | | `related_incidents[].incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `related_incidents[].incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `related_incidents[].incident.service.incident_urgency_rule` above. | | `related_incidents[].incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `related_incidents[].incident.service.support_hours` above. | | `related_incidents[].incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `related_incidents[].incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `related_incidents[].incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `related_incidents[].incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `related_incidents[].incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `related_incidents[].incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `related_incidents[].incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `related_incidents[].incident.service.auto_pause_notifications_parameters` above. | | `related_incidents[].incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `related_incidents[].incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `related_incidents[].incident.alert_grouping.started_at` | string (date-time) | | | | `related_incidents[].incident.alert_grouping.ended_at` | string (date-time) | | | | `related_incidents[].incident.alert_grouping.alert_grouping_active` | boolean | | | | `related_incidents[].incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `related_incidents[].incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `related_incidents[].incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `related_incidents[].incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `related_incidents[].incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `related_incidents[].incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `related_incidents[].incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `related_incidents[].incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `related_incidents[].incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `related_incidents[].incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `related_incidents[].incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `related_incidents[].incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `related_incidents[].incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `related_incidents[].incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `related_incidents[].incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `related_incidents[].incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `related_incidents[].incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `related_incidents[].incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `related_incidents[].incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `related_incidents[].incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `related_incidents[].incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `related_incidents[].incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `related_incidents[].incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `related_incidents[].incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `related_incidents[].incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `related_incidents[].incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `related_incidents[].incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `related_incidents[].incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `related_incidents[].incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `related_incidents[].incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `related_incidents[].incident.service.escalation_policy` above. | | `related_incidents[].incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `related_incidents[].incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `related_incidents[].incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `related_incidents[].incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `related_incidents[].incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `related_incidents[].incident.service.incident_urgency_rule` above. | | `related_incidents[].incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `related_incidents[].incident.service.support_hours` above. | | `related_incidents[].incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `related_incidents[].incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `related_incidents[].incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `related_incidents[].incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `related_incidents[].incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `related_incidents[].incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `related_incidents[].incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `related_incidents[].incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `related_incidents[].incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `related_incidents[].incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `related_incidents[].incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `related_incidents[].incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `related_incidents[].incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `related_incidents[].incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `related_incidents[].incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `related_incidents[].incident.service.auto_pause_notifications_parameters` above. | | `related_incidents[].incident.priority` | object | | | | `related_incidents[].incident.priority.id` | string | | Read-only. | | `related_incidents[].incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `related_incidents[].incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `related_incidents[].incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `related_incidents[].incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `related_incidents[].incident.priority.name` | string | | The user-provided short name of the priority. | | `related_incidents[].incident.priority.description` | string | | The user-provided description of the priority. | | `related_incidents[].incident.resolve_reason` | object | | | | `related_incidents[].incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `related_incidents[].incident.resolve_reason.incident` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.incident` above. | | `related_incidents[].incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `related_incidents[].incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `related_incidents[].incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `related_incidents[].incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `related_incidents[].incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `related_incidents[].incident.incidents_responders[].user` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.channel.notification.user` above. | | `related_incidents[].incident.incidents_responders[].incident` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.incident` above. | | `related_incidents[].incident.incidents_responders[].updated_at` | string | | | | `related_incidents[].incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `related_incidents[].incident.incidents_responders[].requester` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.channel.notification.user` above. | | `related_incidents[].incident.incidents_responders[].requested_at` | string | | | | `related_incidents[].incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `related_incidents[].incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `related_incidents[].incident.responder_requests[].id` | string | | The ID of the responder request. | | `related_incidents[].incident.responder_requests[].incident` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.incident` above. | | `related_incidents[].incident.responder_requests[].requester` | object | | Same fields as `related_incidents[].incident.first_trigger_log_entry.channel.notification.user` above. | | `related_incidents[].incident.responder_requests[].requested_at` | string | | The time the request was made. | | `related_incidents[].incident.responder_requests[].message` | string | | The message sent with the responder request. | | `related_incidents[].incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `related_incidents[].incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `related_incidents[].incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `related_incidents[].incident.responder_requests[].responder_request_targets[].summary` | string | | | | `related_incidents[].incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `related_incidents[].incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `related_incidents[].incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `related_incidents[].incident.body.details` | object | | Additional incident details. | | `related_incidents[].relationships` | array of object | | A list of reasons for why the Incident is considered related. | | `related_incidents[].relationships[].type` | string | | The type of relationship. A relationship outlines the reason why two Incidents are considered related. One of: `machine_learning_inferred`, `service_dependency`. | | `related_incidents[].relationships[].metadata` | one of: object \| object | | | | `related_incidents[].relationships[].metadata.grouping_classification` | string | | (option 1) The classification for why this Related Incident was grouped into this group. Values can be one of: [similar_contents, prior_feedback], where: similar_contents - The Related Incident was due to similar contents of the Incidents. prior_feedback - The Related Incident was determined to be related, based on User feedback or Incident merge/unmerge actions. One of: `similar_contents`, `prior_feedback`. | | `related_incidents[].relationships[].metadata.user_feedback` | object | | (option 1) The feedback provided from Users to influence the machine learning algorithm for future Related Incidents. | | `related_incidents[].relationships[].metadata.user_feedback.positive_feedback_count` | integer | | The total number of times Users agreed that the Incidents are related. | | `related_incidents[].relationships[].metadata.user_feedback.negative_feedback_count` | integer | | The total number of times Users disagreed that the Incidents are related. | | `related_incidents[].relationships[].metadata.dependent_services` | array of object | | (option 2) | | `related_incidents[].relationships[].metadata.dependent_services[].id` | string | | The ID of the Service referenced. Read-only. | | `related_incidents[].relationships[].metadata.dependent_services[].type` | string | | The type of the related Service. One of: `business_service_reference`, `technical_service_reference`. | | `related_incidents[].relationships[].metadata.dependent_services[].self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | | `related_incidents[].relationships[].metadata.supporting_services` | array of object | | (option 2) | | `related_incidents[].relationships[].metadata.supporting_services[].id` | string | | The ID of the Service referenced. Read-only. | | `related_incidents[].relationships[].metadata.supporting_services[].type` | string | | The type of the related Service. One of: `business_service_reference`, `technical_service_reference`. | | `related_incidents[].relationships[].metadata.supporting_services[].self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "related_incidents": [ { "incident": { "id": "PR2P3RW", "created_at": "2020-11-18T13:08:14Z", "self": "https://api.pagerduty.com/incidents/PR2P3RW", "title": "The server is on fire." }, "relationships": [ { "type": "machine_learning_inferred", "metadata": { "grouping_classification": "similar_contents", "user_feedback": { "positive_feedback_count": 12, "negative_feedback_count": 3 } } }, { "type": "service_dependency", "metadata": { "dependent_services": { "id": "P1L1YEE", "type": "business_service_reference", "self": "https://api.pagerduty.com/business_services/P1L1YEE" }, "supporting_services": { "id": "PNGCNV2", "type": "technical_service_reference", "self": "https://api.pagerduty.com/services/PNGCNV2" } } } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/list-incident-alerts # List alerts for an incident `GET https://api.pagerduty.com/incidents/{id}/alerts` List alerts 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `alert_key` | string | | Alert de-duplication key. | | `statuses[]` | string | | Return only alerts with the given statuses. (More status codes may be introduced in the future.) One of: `triggered`, `resolved`. Items must be unique. | | `sort_by` | string | | Used to specify both the field you wish to sort the results on (created_at/resolved_at), 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. One of: `created_at`, `resolved_at`, `created_at:asc`, `created_at:desc`, `resolved_at:asc`, `resolved_at:desc`. Max items: 2. Items must be unique. | | `include[]` | string | | Array of additional details to include. One of: `services`, `first_trigger_log_entries`, `incidents`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of the incident's alerts. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `alerts` | array of object | yes | | | `alerts[].id` | string | | Read-only. | | `alerts[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].type` | string | yes | The type of object being created. One of: `alert`. Default: `alert`. | | `alerts[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].created_at` | string (date-time) | | The date/time the alert was first triggered. Read-only. | | `alerts[].status` | string | | The current status of the alert. One of: `triggered`, `resolved`. | | `alerts[].alert_key` | string | | The alert's de-duplication key. Read-only. | | `alerts[].service` | object | | | | `alerts[].service.id` | string | yes | Read-only. | | `alerts[].service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].service.type` | string | yes | One of: `service_reference`. | | `alerts[].service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].first_trigger_log_entry` | object | | | | `alerts[].first_trigger_log_entry.id` | string | yes | Read-only. | | `alerts[].first_trigger_log_entry.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].first_trigger_log_entry.type` | string | yes | One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `alerts[].first_trigger_log_entry.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].first_trigger_log_entry.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].incident` | object | | | | `alerts[].incident.id` | string | yes | Read-only. | | `alerts[].incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].incident.type` | string | yes | One of: `incident_reference`. | | `alerts[].incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].suppressed` | boolean | | Whether or not an alert is suppressed. Suppressed alerts are not created with a parent incident. Read-only. Default: `false`. | | `alerts[].severity` | string | | The magnitude of the problem as reported by the monitoring tool. Read-only. One of: `info`, `warning`, `error`, `critical`. | | `alerts[].integration` | object | | | | `alerts[].integration.id` | string | yes | Read-only. | | `alerts[].integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `alerts[].integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].body` | object | | A JSON object containing data describing the alert. Read-only. | | `alerts[].body.type` | string | | The type of the body. One of: `alert_body`. | | `alerts[].body.contexts` | array of object | | Contexts to be included with the body such as links to graphs or images. Read-only. | | `alerts[].body.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `alerts[].body.contexts[].href` | string | | The link's target url. | | `alerts[].body.contexts[].src` | string | | The image's source url. | | `alerts[].body.contexts[].text` | string | | The alternate display for an image. | | `alerts[].body.details` | object | | An arbitrary JSON object or string containing any data explaining the nature of the alert. Read-only. | Example: Response Example ```json { "alerts": [ { "id": "PT4KHLK", "type": "alert", "summary": "The server is on fire.", "self": "https://api.pagerduty.com/incidents/PT4KHLK/alerts/PXPGF42", "html_url": "https://subdomain.pagerduty.com/alerts/PXPGF42", "created_at": "2015-10-06T21:30:42Z", "status": "resolved", "alert_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" }, "body": { "type": "alert_body", "contexts": [ { "type": "link" } ], "details": { "customKey": "Server is on fire!", "customKey2": "Other stuff!" } }, "incident": { "id": "PT4KHLK", "type": "incident_reference" }, "suppressed": false, "severity": "critical", "integration": { "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" } } ], "limit": 1, "offset": 0, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/list-incident-log-entries # List log entries for an incident `GET https://api.pagerduty.com/incidents/{id}/log_entries` 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | | `is_overview` | boolean | | If `true`, will return a subset of log entries that show only the most important changes to the incident. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `incidents`, `services`, `channels`, `teams`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of the incident's log entries. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `log_entries` | array of one of: object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object | yes | | | `log_entries[].id` | string | | (option 1) Read-only. | | `log_entries[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 1) One of: `acknowledgement_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 1) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 1) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `log_entries[].channel.type` | string | | (NagiosChannel) Will be `nagios` | | `log_entries[].channel.summary` | string | | (NagiosChannel) Same as `host` | | `log_entries[].channel.host` | string | | (NagiosChannel) Nagios host. | | `log_entries[].channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `log_entries[].channel.state` | string | | (NagiosChannel) State that caused the event. | | `log_entries[].channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `log_entries[].channel.type` | string | | (APIChannel) Will be `api` | | `log_entries[].channel.summary` | string | | (APIChannel) Same as `description` | | `log_entries[].channel.service_key` | string | | (APIChannel) API service key. | | `log_entries[].channel.description` | string | | (APIChannel) Description of the event. | | `log_entries[].channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `log_entries[].channel.details` | object | | (APIChannel) Additional details of the incident. | | `log_entries[].channel.type` | string | | (EmailChannel) Will be `email` | | `log_entries[].channel.summary` | string | | (EmailChannel) Same as `subject` | | `log_entries[].channel.to` | string | | (EmailChannel) To address of the email. | | `log_entries[].channel.from` | string | | (EmailChannel) From address of the email. | | `log_entries[].channel.subject` | string | | (EmailChannel) Subject of the email. | | `log_entries[].channel.body` | string | | (EmailChannel) Body of the email. | | `log_entries[].channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `log_entries[].channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `log_entries[].channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `log_entries[].channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `log_entries[].channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `log_entries[].channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `log_entries[].channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `log_entries[].channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `log_entries[].channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `log_entries[].channel.type` | string | yes | type. | | `log_entries[].channel.user` | object | | | | `log_entries[].channel.team` | object | | | | `log_entries[].channel.notification` | object | | | | `log_entries[].channel.notification.id` | string | | Read-only. | | `log_entries[].channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `log_entries[].channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `log_entries[].channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `log_entries[].channel.notification.user` | object | | | | `log_entries[].channel.notification.user.id` | string | yes | Read-only. | | `log_entries[].channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].channel.notification.user.type` | string | yes | One of: `user_reference`. | | `log_entries[].channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `log_entries[].channel.notification.status` | string | | | | `log_entries[].channel.notification.` | string | | | | `log_entries[].channel.channel` | object | | channel. | | `log_entries[].channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.customer_fields[].id` | string | | | | `log_entries[].channel.changeset.customer_fields[].name` | string | | | | `log_entries[].channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `log_entries[].channel.changeset.customer_fields[].namespace` | string | | | | `log_entries[].channel.changeset.customer_fields[].old_value` | string \| null | | | | `log_entries[].channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.application_fields[].id` | string | | | | `log_entries[].channel.changeset.application_fields[].name` | string | | | | `log_entries[].channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `log_entries[].channel.changeset.application_fields[].namespace` | string | | | | `log_entries[].channel.changeset.application_fields[].old_value` | string \| null | | | | `log_entries[].channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `log_entries[].channel.changeset.customer_schema` | object | | | | `log_entries[].channel.changeset.customer_schema.old_value` | string \| null | | | | `log_entries[].agent` | object | | (option 1) | | `log_entries[].agent.id` | string | yes | Read-only. | | `log_entries[].agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `log_entries[].agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].note` | string | | (option 1) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 1) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 1) | | `log_entries[].service.id` | string | yes | Read-only. | | `log_entries[].service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].service.type` | string | yes | One of: `service_reference`. | | `log_entries[].service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].incident` | object | | (option 1) | | `log_entries[].incident.id` | string | yes | Read-only. | | `log_entries[].incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].incident.type` | string | yes | One of: `incident_reference`. | | `log_entries[].incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].teams` | array of object | | (option 1) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 1) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 1) String record of custom field updates. | | `log_entries[].acknowledgement_timeout` | integer | | (option 1) Duration for which the acknowledgement lasts, in seconds. Services can contain an `acknowledgement_timeout` property, which specifies the length of time acknowledgements should last for. Each time an incident is acknowledged, this timeout is copied into the acknowledgement log entry. This property is optional, as older log entries may not contain it. It may also be `null`, as acknowledgements can be performed on incidents whose services have no `acknowledgement_timeout` set. | | `log_entries[].id` | string | | (option 2) Read-only. | | `log_entries[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 2) One of: `annotate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 2) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 2) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 2) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 2) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 2) String record of custom field updates. | | `log_entries[].id` | string | | (option 3) Read-only. | | `log_entries[].summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 3) One of: `assign_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 3) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 3) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 3) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 3) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 3) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 3) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 3) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 3) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 3) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 3) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 3) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 4) Read-only. | | `log_entries[].summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 4) One of: `delegate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 4) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 4) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 4) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 4) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 4) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 4) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 4) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 4) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 4) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 4) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 4) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 5) Read-only. | | `log_entries[].summary` | string \| null | | (option 5) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 5) One of: `escalate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 5) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 5) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 5) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 5) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 5) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 5) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 5) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 5) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 5) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 5) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 5) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 5) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 5) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 6) Read-only. | | `log_entries[].summary` | string \| null | | (option 6) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 6) One of: `exhaust_escalation_path_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 6) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 6) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 6) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 6) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 6) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 6) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 6) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 6) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 6) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 6) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 6) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 6) String record of custom field updates. | | `log_entries[].id` | string | | (option 7) Read-only. | | `log_entries[].summary` | string \| null | | (option 7) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 7) One of: `notify_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 7) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 7) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 7) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 7) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 7) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 7) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 7) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 7) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 7) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 7) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 7) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 7) String record of custom field updates. | | `log_entries[].user` | object | | (option 7) Same fields as `log_entries[].channel.notification.user` above. | | `log_entries[].id` | string | | (option 8) Read-only. | | `log_entries[].summary` | string \| null | | (option 8) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 8) One of: `reach_ack_limit_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 8) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 8) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 8) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 8) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 8) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 8) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 8) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 8) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 8) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 8) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 8) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 8) String record of custom field updates. | | `log_entries[].id` | string | | (option 9) Read-only. | | `log_entries[].summary` | string \| null | | (option 9) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 9) One of: `reach_trigger_limit_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 9) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 9) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 9) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 9) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 9) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 9) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 9) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 9) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 9) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 9) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 9) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 9) String record of custom field updates. | | `log_entries[].id` | string | | (option 10) Read-only. | | `log_entries[].summary` | string \| null | | (option 10) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 10) One of: `repeat_escalation_path_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 10) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 10) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 10) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 10) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 10) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 10) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 10) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 10) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 10) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 10) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 10) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 10) String record of custom field updates. | | `log_entries[].id` | string | | (option 11) Read-only. | | `log_entries[].summary` | string \| null | | (option 11) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 11) One of: `resolve_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 11) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 11) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 11) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 11) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 11) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 11) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 11) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 11) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 11) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 11) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 11) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 11) String record of custom field updates. | | `log_entries[].id` | string | | (option 12) Read-only. | | `log_entries[].summary` | string \| null | | (option 12) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 12) One of: `snooze_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 12) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 12) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 12) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 12) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 12) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 12) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 12) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 12) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 12) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 12) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 12) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 12) String record of custom field updates. | | `log_entries[].changed_actions` | array of object | | (option 12) | | `log_entries[].changed_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `log_entries[].changed_actions[].at` | string (date-time) | yes | | | `log_entries[].changed_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `log_entries[].id` | string | | (option 13) Read-only. | | `log_entries[].summary` | string \| null | | (option 13) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 13) One of: `trigger_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 13) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 13) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 13) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 13) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 13) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 13) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 13) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 13) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 13) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 13) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 13) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 13) String record of custom field updates. | | `log_entries[].id` | string | | (option 14) Read-only. | | `log_entries[].summary` | string \| null | | (option 14) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 14) One of: `unacknowledge_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 14) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 14) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 14) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 14) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 14) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 14) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 14) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 14) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 14) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 14) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 14) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 14) String record of custom field updates. | | `log_entries[].id` | string | | (option 15) Read-only. | | `log_entries[].summary` | string \| null | | (option 15) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 15) One of: `urgency_change_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 15) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 15) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 15) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 15) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 15) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 15) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 15) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 15) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 15) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 15) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 15) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 15) String record of custom field updates. | | `log_entries[].id` | string | | (option 16) Read-only. | | `log_entries[].summary` | string \| null | | (option 16) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 16) One of: `field_value_change_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 16) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 16) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 16) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 16) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 16) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 16) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 16) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 16) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 16) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 16) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 16) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 16) String record of custom field updates. | | `log_entries[].id` | string | | (option 17) Read-only. | | `log_entries[].summary` | string \| null | | (option 17) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 17) One of: `custom_field_value_change_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 17) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 17) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 17) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 17) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 17) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 17) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 17) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 17) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 17) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 17) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 17) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 17) String record of custom field updates. | Example: Response Example ```json { "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" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/list-incident-notes # List notes for an incident `GET https://api.pagerduty.com/incidents/{id}/notes` 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of notes. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notes` | array of object | yes | | | `notes[].id` | string | | Read-only. | | `notes[].user` | object | | | | `notes[].user.id` | string | yes | Read-only. | | `notes[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notes[].user.type` | string | yes | One of: `user_reference`, `bot_user_reference`. | | `notes[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notes[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notes[].channel` | object | | The means by which this Note was created. Has different formats depending on type. Read-only. | | `notes[].channel.summary` | string | yes | A string describing the source of the Note. Read-only. | | `notes[].channel.id` | string | | Read-only. | | `notes[].channel.type` | string | | A string that determines the schema of the object. Read-only. | | `notes[].channel.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `notes[].channel.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notes[].content` | string | yes | The note content. | | `notes[].created_at` | string (date-time) | | The time at which the note was submitted. Read-only. | | `notes[].updated_at` | string (date-time) | | The time at which the note was last updated. Read-only. | Example: Response Example ```json { "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" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/list-incidents # List incidents `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. Maximum of 100. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `date_range` | string | | When set to all, the since and until parameters and defaults are ignored. One of: `all`. | | `incident_key` | string | | 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. | | `service_ids[]` | array of string | | Returns only the incidents associated with the passed service(s). This expects one or more service IDs. Items must be unique. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `user_ids[]` | array of string | | 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. Items must be unique. | | `urgencies[]` | string | | Array of the urgencies of the incidents to be returned. Defaults to all urgencies. Account must have the `urgencies` ability to do this. One of: `high`, `low`. Items must be unique. | | `time_zone` | string (tzinfo) | | Time zone used to render timestamps and to interpret `since/until` values before filtering. Rendering defaults to UTC if omitted. `since/until` default to the account's time zone if omitted. | | `statuses[]` | string | | 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.) One of: `triggered`, `acknowledged`, `resolved`. Items must be unique. | | `sort_by` | array of string | | 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. Max items: 2. Items must be unique. | | `include[]` | string | | Array of additional details to include. One of: `acknowledgers`, `agents`, `assignees`, `conference_bridge`, `escalation_policies`, `first_trigger_log_entries`, `priorities`, `services`, `teams`, `users`. Items must be unique. | | `since` | string | | The start of the date range over which you want to search. Maximum range is 6 months and default is 1 month. | | `until` | string | | The end of the date range over which you want to search. Maximum range is 6 months and default is 1 month. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of incidents. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `incidents` | array of object | yes | | | `incidents[].id` | string | | Read-only. | | `incidents[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incidents[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incidents[].title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incidents[].created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incidents[].updated_at` | string (date-time) | | The time the incident was last modified. | | `incidents[].status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incidents[].incident_key` | string | | The incident's de-duplication key. Read-only. | | `incidents[].service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incidents[].service.id` | string | yes | (option 1) Read-only. | | `incidents[].service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.type` | string | yes | (option 1) One of: `service_reference`. | | `incidents[].service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.id` | string | | (option 2) Read-only. | | `incidents[].service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.name` | string | | (option 2) The name of the service. | | `incidents[].service.description` | string | | (option 2) The user-provided description of the service. | | `incidents[].service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incidents[].service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].service.escalation_policy` | object | yes | (option 2) | | `incidents[].service.escalation_policy.id` | string | yes | Read-only. | | `incidents[].service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incidents[].service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incidents[].service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incidents[].service.teams[].id` | string | yes | Read-only. | | `incidents[].service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].service.integrations[].id` | string | yes | Read-only. | | `incidents[].service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.incident_urgency_rule` | object | | (option 2) | | `incidents[].service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incidents[].service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incidents[].service.incident_urgency_rule.during_support_hours` | object | | | | `incidents[].service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incidents[].service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incidents[].service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incidents[].service.incident_urgency_rule.during_support_hours` above. | | `incidents[].service.support_hours` | object | | (option 2) | | `incidents[].service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incidents[].service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incidents[].service.support_hours.days_of_week` | array of integer | | Read-only. | | `incidents[].service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incidents[].service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incidents[].service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incidents[].service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incidents[].service.addons[].id` | string | yes | Read-only. | | `incidents[].service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].service.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incidents[].service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incidents[].service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incidents[].service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incidents[].service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incidents[].assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incidents[].assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incidents[].assignments[].assignee` | one of: object \| object | yes | | | `incidents[].assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incidents[].assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incidents[].assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.id` | string | | (option 2) Read-only. | | `incidents[].assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incidents[].assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incidents[].assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incidents[].last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incidents[].resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incidents[].first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incidents[].first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incidents[].first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incidents[].first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incidents[].first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incidents[].first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incidents[].first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incidents[].first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incidents[].first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incidents[].first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incidents[].first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incidents[].first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incidents[].first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incidents[].first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incidents[].first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incidents[].first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incidents[].first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incidents[].first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incidents[].first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incidents[].first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incidents[].first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incidents[].first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incidents[].first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incidents[].first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incidents[].first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incidents[].first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incidents[].first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incidents[].first_trigger_log_entry.channel.type` | string | yes | type. | | `incidents[].first_trigger_log_entry.channel.user` | object | | | | `incidents[].first_trigger_log_entry.channel.team` | object | | | | `incidents[].first_trigger_log_entry.channel.notification` | object | | | | `incidents[].first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incidents[].first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.user` | object | | | | `incidents[].first_trigger_log_entry.channel.notification.user.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `incidents[].first_trigger_log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incidents[].first_trigger_log_entry.channel.notification.status` | string | | | | `incidents[].first_trigger_log_entry.channel.notification.` | string | | | | `incidents[].first_trigger_log_entry.channel.channel` | object | | channel. | | `incidents[].first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.agent` | object | | (option 2) | | `incidents[].first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incidents[].first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incidents[].first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incidents[].first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incidents[].first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incidents[].first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incidents[].first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incidents[].first_trigger_log_entry.service` | object | | (option 2) | | `incidents[].first_trigger_log_entry.service.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `incidents[].first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.incident` | object | | (option 2) | | `incidents[].first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incidents[].first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incidents[].first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incidents[].first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incidents[].first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incidents[].alert_counts` | object | | | | `incidents[].alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incidents[].alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incidents[].alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incidents[].is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incidents[].incident_type` | object | | The incident type of the incident. | | `incidents[].incident_type.name` | string | | The name of the Incident Type. | | `incidents[].escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incidents[].escalation_policy.id` | string | yes | (option 1) Read-only. | | `incidents[].escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incidents[].escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.id` | string | | (option 2) Read-only. | | `incidents[].escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incidents[].escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incidents[].escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incidents[].escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incidents[].escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incidents[].escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incidents[].escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incidents[].escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incidents[].escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incidents[].escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incidents[].escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incidents[].escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incidents[].escalation_policy.services[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incidents[].escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incidents[].escalation_policy.teams[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incidents[].teams[].id` | string | yes | (option 1) Read-only. | | `incidents[].teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incidents[].teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams[].id` | string | | (option 2) Read-only. | | `incidents[].teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incidents[].teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incidents[].teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incidents[].teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incidents[].pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incidents[].pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incidents[].pending_actions[].at` | string (date-time) | yes | | | `incidents[].pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incidents[].acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incidents[].acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incidents[].acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incidents[].acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incidents[].acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incidents[].acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incidents[].acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incidents[].acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incidents[].acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incidents[].service.escalation_policy` above. | | `incidents[].acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incidents[].service.incident_urgency_rule` above. | | `incidents[].acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incidents[].service.support_hours` above. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incidents[].service.auto_pause_notifications_parameters` above. | | `incidents[].alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incidents[].alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incidents[].alert_grouping.started_at` | string (date-time) | | | | `incidents[].alert_grouping.ended_at` | string (date-time) | | | | `incidents[].alert_grouping.alert_grouping_active` | boolean | | | | `incidents[].last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incidents[].last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.id` | string | | (option 2) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].last_status_change_by.color` | string | | (option 2) The schedule color. | | `incidents[].last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incidents[].last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].last_status_change_by.teams[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].last_status_change_by.id` | string | | (option 3) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.name` | string | | (option 3) The name of the service. | | `incidents[].last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incidents[].last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incidents[].last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incidents[].service.escalation_policy` above. | | `incidents[].last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incidents[].last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incidents[].last_status_change_by.teams[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incidents[].service.incident_urgency_rule` above. | | `incidents[].last_status_change_by.support_hours` | object | | (option 3) Same fields as `incidents[].service.support_hours` above. | | `incidents[].last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incidents[].last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incidents[].last_status_change_by.addons[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incidents[].last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incidents[].service.auto_pause_notifications_parameters` above. | | `incidents[].priority` | object | | | | `incidents[].priority.id` | string | | Read-only. | | `incidents[].priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incidents[].priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].priority.name` | string | | The user-provided short name of the priority. | | `incidents[].priority.description` | string | | The user-provided description of the priority. | | `incidents[].resolve_reason` | object | | | | `incidents[].resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incidents[].resolve_reason.incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incidents[].conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incidents[].conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incidents[].incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incidents[].incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incidents[].incidents_responders[].user` | object | | Same fields as `incidents[].first_trigger_log_entry.channel.notification.user` above. | | `incidents[].incidents_responders[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].incidents_responders[].updated_at` | string | | | | `incidents[].incidents_responders[].message` | string | | The message sent with the responder request. | | `incidents[].incidents_responders[].requester` | object | | Same fields as `incidents[].first_trigger_log_entry.channel.notification.user` above. | | `incidents[].incidents_responders[].requested_at` | string | | | | `incidents[].incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incidents[].responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incidents[].responder_requests[].id` | string | | The ID of the responder request. | | `incidents[].responder_requests[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].responder_requests[].requester` | object | | Same fields as `incidents[].first_trigger_log_entry.channel.notification.user` above. | | `incidents[].responder_requests[].requested_at` | string | | The time the request was made. | | `incidents[].responder_requests[].message` | string | | The message sent with the responder request. | | `incidents[].responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incidents[].responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incidents[].responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incidents[].responder_requests[].responder_request_targets[].summary` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incidents[].first_trigger_log_entry.channel.notification.user` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incidents[].first_trigger_log_entry.channel.notification.user` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incidents[].urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incidents[].body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incidents[].body.details` | object | | Additional incident details. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/merge-incidents # Merge incidents `PUT https://api.pagerduty.com/incidents/{id}/merge` Merge a list of source incidents into the target [incident](https://docs.pagerduty.com/developer/api-concepts#incidents). After the merge is performed the target incident will contain the source incidents' [alerts](https://docs.pagerduty.com/developer/api-concepts#alerts), and the source incidents will be resolved. Only incidents that have alerts or incidents that were created manually in the UI can be merged. Open incidents cannot be merged into a resolved incident. The target incident must be open. An incident cannot have more than 1000 alerts. The server will return an error if merging the source incidents will result in the target incident having more than 1000 alerts. Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `source_incidents` | array of object | yes | The source incidents that will be merged into the target incident and resolved. | | `source_incidents[].id` | string | yes | Read-only. | | `source_incidents[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `source_incidents[].type` | string | yes | One of: `incident_reference`. | | `source_incidents[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `source_incidents[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "source_incidents": [ { "id": "P8JOGX7", "type": "incident_reference" }, { "id": "PPVZH9X", "type": "incident_reference" } ] } ``` ## Response 200 The target incident, which now contains all the alerts from the source incident. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | | | `incident.id` | string | yes | Read-only. | | `incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.type` | string | yes | One of: `incident_reference`. | | `incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "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" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/put-incident-manual-business-service-association # Manually change an Incident's Impact on a Business Service. `PUT https://api.pagerduty.com/incidents/{id}/business_services/{business_service_id}/impacts` Change Impact of an Incident on a Business Service. Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `business_service_id` | string | yes | The business service ID. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The `impacted` relation will cause the Business Service and any Services that it supports to become impacted by this incident. The `not_impacted` relation will remove the Incident's Impact from the specified Business Service. The effect of adding or removing Impact to a Business Service in this way will also change the propagation of Impact to other Services supported by that Business Service. | Field | Type | Required | Description | |---|---|---|---| | `relation` | string | yes | One of: `impacted`, `not_impacted`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `relation` | string | | One of: `impacted`, `not_impacted`. | Example: Response Example ```json { "relation": "impacted" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/remove-incident-notification-subscribers # Remove Notification Subscriber `POST https://api.pagerduty.com/incidents/{id}/status_updates/unsubscribe` Unsubscribes the matching Subscribers from Incident Status Update Notifications. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to unsubscribe. | Field | Type | Required | Description | |---|---|---|---| | `subscribers` | array of object | yes | Min items: 1. Items must be unique. | | `subscribers[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscribers[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | Example: Request Example ```json { "subscribers": [ { "subscriber_id": "PD1234", "subscriber_type": "team" }, { "subscriber_id": "PD1234", "subscriber_type": "user" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `deleted_count` | number | yes | | | `unauthorized_count` | number | yes | | | `non_existent_count` | number | yes | | Example: Response Example ```json { "deleted_count": 1, "unauthorized_count": 1, "non_existent_count": 0 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/set-incident-field-values # Update Custom Field Values `PUT https://api.pagerduty.com/incidents/{id}/custom_fields/values` Set custom field values for an incident. Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of one of: object \| object | yes | | | `custom_fields[].name` | string | | (Value by Field Name) The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | | (Value by Field Name) | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | | `custom_fields[].id` | string | | (Value by Field ID) The ID of the Field. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | | (Value by Field ID) | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Request Example ```json { "custom_fields": [ { "name": "environment", "value": "production" } ] } ``` Example: Request Example ```json { "custom_fields": [ { "id": "PT4KHEE", "value": "production" } ] } ``` Example: Request Example ```json { "custom_fields": [ { "id": "PT4KHEE", "value": [ "production", "staging" ] } ] } ``` ## Response 201 Custom field values were updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of object | yes | | | `custom_fields[].id` | string | yes | Id of the field. | | `custom_fields[].name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].type` | string | yes | Determines the type of the reference. One of: `field_value`. | | `custom_fields[].display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `custom_fields[].field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `custom_fields[].data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `custom_fields[].description` | string \| null | yes | A description of the data this field contains. Max length: 1000. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | yes | | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Response Example ```json { "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" } ] } ``` Example: Response Example ```json { "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" } ] } ``` Example: Response Example ```json { "custom_fields": [ { "id": "PT4KHEE", "type": "field_value", "name": "environment", "display_name": "Runtime Environment", "description": "environment where incident occurred", "data_type": "string", "field_type": "multi_value_fixed", "value": [ "production", "staging" ] } ] } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident # Update an incident `PUT https://api.pagerduty.com/incidents/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | The parameters of the incident to update. | | `incident.type` | string | yes | The incident type. One of: `incident`, `incident_reference`. | | `incident.status` | string | | The new status of the incident. If the incident is currently resolved, setting the status to "triggered" or "acknowledged" will reopen it. When reopening an incident to the "triggered" status, it will be assigned based on the assignees or escalation_policy fields in the request, otherwise it will be assigned to the current Escalation Policy. When reopening an incident to the "acknowledged" status, it will be assigned to the current user. One of: `resolved`, `acknowledged`, `triggered`. | | `incident.priority` | one of: object \| string | | The priority of the incident. Can be provided as a priority object or a string matching a priority name. If a string is provided, the highest priority with a matching name will be used. | | `incident.priority.id` | string | yes | (option 1) The ID of the priority. | | `incident.priority.name` | string | | (option 1) The user-provided short name of the priority. | | `incident.priority.type` | string | yes | (option 1) The type of the reference. One of: `priority`, `priority_reference`. | | `incident.resolution` | string | | The resolution for this incident. This field is used only when setting the incident status to resolved. The value provided here is added to the incident’s 'Resolve' log entry as a note and will not be displayed directly in the UI. | | `incident.title` | string | | The new title of the incident. | | `incident.escalation_level` | integer | | Escalate the incident to this level in the escalation policy. | | `incident.assignments` | array of object | | Assign the incident to these assignees. | | `incident.assignments[].assignee` | object | | | | `incident.assignments[].assignee.id` | string | yes | Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_type` | object | | | | `incident.incident_type.id` | string | | Read-only. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | object | | | | `incident.escalation_policy.id` | string | yes | Read-only. | | `incident.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.urgency` | string | | The urgency of the incident. One of: `high`, `low`. | | `incident.conference_bridge` | object | | | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incident.service` | object | | Assign the incident to this service. | | `incident.service.id` | string | yes | The ID of the service. | | `incident.service.type` | string | yes | The type of the reference. One of: `service_reference`. | Example: Request Example ```json { "incident": { "type": "incident_reference", "status": "acknowledged" } } ``` ## Response 200 The incident was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `incident` | object | yes | | | `incident.id` | string | | Read-only. | | `incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incident.title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incident.created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incident.updated_at` | string (date-time) | | The time the incident was last modified. | | `incident.status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incident.incident_key` | string | | The incident's de-duplication key. Read-only. | | `incident.service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incident.service.id` | string | yes | (option 1) Read-only. | | `incident.service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 1) One of: `service_reference`. | | `incident.service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.id` | string | | (option 2) Read-only. | | `incident.service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incident.service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.name` | string | | (option 2) The name of the service. | | `incident.service.description` | string | | (option 2) The user-provided description of the service. | | `incident.service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incident.service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incident.service.escalation_policy` | object | yes | (option 2) Same fields as `incident.escalation_policy` above. | | `incident.service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incident.service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incident.service.teams[].id` | string | yes | Read-only. | | `incident.service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.teams[].type` | string | yes | One of: `team_reference`. | | `incident.service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.service.integrations[].id` | string | yes | Read-only. | | `incident.service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.incident_urgency_rule` | object | | (option 2) | | `incident.service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.during_support_hours` | object | | | | `incident.service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incident.service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incident.service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incident.service.incident_urgency_rule.during_support_hours` above. | | `incident.service.support_hours` | object | | (option 2) | | `incident.service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incident.service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incident.service.support_hours.days_of_week` | array of integer | | Read-only. | | `incident.service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incident.service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incident.service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incident.service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incident.service.addons[].id` | string | yes | Read-only. | | `incident.service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.service.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.service.addons[].name` | string | | The user entered name of the Addon. | | `incident.service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incident.service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incident.service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incident.service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incident.service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incident.assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incident.assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incident.assignments[].assignee` | one of: object \| object | yes | | | `incident.assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.id` | string | | (option 2) Read-only. | | `incident.assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incident.assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incident.assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incident.assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incident.assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incident.last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incident.resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incident.first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incident.first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incident.first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incident.first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incident.first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incident.first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incident.first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incident.first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incident.first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incident.first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incident.first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incident.first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incident.first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incident.first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incident.first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incident.first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incident.first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incident.first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incident.first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incident.first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incident.first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incident.first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incident.first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incident.first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incident.first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incident.first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incident.first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incident.first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incident.first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incident.first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incident.first_trigger_log_entry.channel.type` | string | yes | type. | | `incident.first_trigger_log_entry.channel.user` | object | | | | `incident.first_trigger_log_entry.channel.team` | object | | | | `incident.first_trigger_log_entry.channel.notification` | object | | | | `incident.first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incident.first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incident.first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incident.first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incident.first_trigger_log_entry.channel.notification.user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incident.first_trigger_log_entry.channel.notification.status` | string | | | | `incident.first_trigger_log_entry.channel.notification.` | string | | | | `incident.first_trigger_log_entry.channel.channel` | object | | channel. | | `incident.first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incident.first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incident.first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incident.first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incident.first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incident.first_trigger_log_entry.agent` | object | | (option 2) | | `incident.first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incident.first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incident.first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incident.first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incident.first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incident.first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incident.first_trigger_log_entry.service` | object | | (option 2) | | `incident.first_trigger_log_entry.service.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `incident.first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.incident` | object | | (option 2) | | `incident.first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incident.first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incident.first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incident.first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incident.first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incident.first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incident.first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incident.alert_counts` | object | | | | `incident.alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incident.alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incident.alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incident.is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incident.incident_type` | object | | The incident type of the incident. | | `incident.incident_type.name` | string | | The name of the Incident Type. | | `incident.escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incident.escalation_policy.id` | string | yes | (option 1) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.id` | string | | (option 2) Read-only. | | `incident.escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incident.escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incident.escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incident.escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incident.escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incident.escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incident.escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incident.escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incident.escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incident.escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incident.escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incident.escalation_policy.services[].id` | string | yes | Read-only. | | `incident.escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incident.escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incident.escalation_policy.teams[].id` | string | yes | Read-only. | | `incident.escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incident.escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incident.teams[].id` | string | yes | (option 1) Read-only. | | `incident.teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incident.teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].id` | string | | (option 2) Read-only. | | `incident.teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incident.teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incident.teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incident.teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incident.pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incident.pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incident.pending_actions[].at` | string (date-time) | yes | | | `incident.pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incident.acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incident.acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incident.acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incident.acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incident.acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incident.acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incident.acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incident.acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incident.acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incident.escalation_policy` above. | | `incident.acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incident.acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incident.acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incident.acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incident.alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incident.alert_grouping.started_at` | string (date-time) | | | | `incident.alert_grouping.ended_at` | string (date-time) | | | | `incident.alert_grouping.alert_grouping_active` | boolean | | | | `incident.last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incident.last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.id` | string | | (option 2) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incident.last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incident.last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incident.last_status_change_by.color` | string | | (option 2) The schedule color. | | `incident.last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incident.last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incident.last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incident.last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incident.last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incident.last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incident.last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incident.last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incident.last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incident.last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incident.last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incident.last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incident.last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incident.last_status_change_by.id` | string | | (option 3) Read-only. | | `incident.last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incident.last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.name` | string | | (option 3) The name of the service. | | `incident.last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incident.last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incident.last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incident.last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incident.last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incident.last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incident.last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incident.escalation_policy` above. | | `incident.last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incident.last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incident.last_status_change_by.teams[].id` | string | yes | Read-only. | | `incident.last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incident.last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incident.last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incident.last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incident.last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incident.service.incident_urgency_rule` above. | | `incident.last_status_change_by.support_hours` | object | | (option 3) Same fields as `incident.service.support_hours` above. | | `incident.last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incident.last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incident.last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incident.last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incident.last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incident.last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incident.last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incident.last_status_change_by.addons[].id` | string | yes | Read-only. | | `incident.last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incident.last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incident.last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incident.last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incident.last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incident.last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incident.last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incident.last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incident.last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incident.last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incident.last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incident.last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incident.last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incident.last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incident.last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incident.service.auto_pause_notifications_parameters` above. | | `incident.priority` | object | | | | `incident.priority.id` | string | | Read-only. | | `incident.priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incident.priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incident.priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incident.priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incident.priority.name` | string | | The user-provided short name of the priority. | | `incident.priority.description` | string | | The user-provided description of the priority. | | `incident.resolve_reason` | object | | | | `incident.resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incident.resolve_reason.incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incident.conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incident.conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incident.incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.incidents_responders[].user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.incidents_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.incidents_responders[].updated_at` | string | | | | `incident.incidents_responders[].message` | string | | The message sent with the responder request. | | `incident.incidents_responders[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.incidents_responders[].requested_at` | string | | | | `incident.incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incident.responder_requests[].id` | string | | The ID of the responder request. | | `incident.responder_requests[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].requested_at` | string | | The time the request was made. | | `incident.responder_requests[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incident.responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incident.responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incident.responder_requests[].responder_request_targets[].summary` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incident.first_trigger_log_entry.incident` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incident.assignments[].assignee` above. | | `incident.responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incident.responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incident.urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incident.body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incident.body.details` | object | | Additional incident details. | Example: Response Example ```json { "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" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident-alert # Update an alert `PUT https://api.pagerduty.com/incidents/{id}/alerts/{alert_id}` Resolve an alert or associate an alert with a new parent incident. An incident represents a problem or an issue that needs to be addressed and resolved. When a service sends an event to PagerDuty, an alert and corresponding incident is triggered in PagerDuty. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `alert_id` | string | yes | The id of the alert to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) The parameters of the alert to update. | Field | Type | Required | Description | |---|---|---|---| | `alert` | object | yes | | | `alert.status` | string | | One of: `resolved`, `triggered`. | | `alert.incident` | object | | | | `alert.incident.id` | string | yes | | | `alert.incident.type` | string | | One of: `incident_reference`. | Example: Request Example ```json { "alert": { "type": "alert", "status": "resolved", "incident": { "id": "PEYSGVF", "type": "incident_reference" } } } ``` ## Response 200 The alert that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `alert` | object | yes | | | `alert.id` | string | | Read-only. | | `alert.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.type` | string | yes | The type of object being created. One of: `alert`. Default: `alert`. | | `alert.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.created_at` | string (date-time) | | The date/time the alert was first triggered. Read-only. | | `alert.status` | string | | The current status of the alert. One of: `triggered`, `resolved`. | | `alert.alert_key` | string | | The alert's de-duplication key. Read-only. | | `alert.service` | object | | | | `alert.service.id` | string | yes | Read-only. | | `alert.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.service.type` | string | yes | One of: `service_reference`. | | `alert.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.first_trigger_log_entry` | object | | | | `alert.first_trigger_log_entry.id` | string | yes | Read-only. | | `alert.first_trigger_log_entry.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.first_trigger_log_entry.type` | string | yes | One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `alert.first_trigger_log_entry.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.first_trigger_log_entry.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.incident` | object | | | | `alert.incident.id` | string | yes | Read-only. | | `alert.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.incident.type` | string | yes | One of: `incident_reference`. | | `alert.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.suppressed` | boolean | | Whether or not an alert is suppressed. Suppressed alerts are not created with a parent incident. Read-only. Default: `false`. | | `alert.severity` | string | | The magnitude of the problem as reported by the monitoring tool. Read-only. One of: `info`, `warning`, `error`, `critical`. | | `alert.integration` | object | | | | `alert.integration.id` | string | yes | Read-only. | | `alert.integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alert.integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `alert.integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alert.integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alert.body` | object | | A JSON object containing data describing the alert. Read-only. | | `alert.body.type` | string | | The type of the body. One of: `alert_body`. | | `alert.body.contexts` | array of object | | Contexts to be included with the body such as links to graphs or images. Read-only. | | `alert.body.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `alert.body.contexts[].href` | string | | The link's target url. | | `alert.body.contexts[].src` | string | | The image's source url. | | `alert.body.contexts[].text` | string | | The alternate display for an image. | | `alert.body.details` | object | | An arbitrary JSON object or string containing any data explaining the nature of the alert. Read-only. | Example: Request Example ```json { "alert": { "type": "alert", "status": "resolved", "incident": { "id": "PEYSGVF", "type": "incident_reference" }, "body": { "type": "alert_body", "contexts": [ { "type": "link" } ], "details": { "customKey": "Server is on fire!", "customKey2": "Other stuff!" } } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident-alerts # Manage alerts `PUT https://api.pagerduty.com/incidents/{id}/alerts` Resolve multiple alerts or associate them with different incidents. An incident represents a problem or an issue that needs to be addressed and resolved. An alert represents a digital signal that was emitted to PagerDuty by the monitoring systems that detected or identified the issue. A maximum of 250 alerts may be updated at a time. If more than this number of alerts are given, the API will respond with status 413 (Request Entity Too Large). For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `alerts` | array of object | yes | An array of alerts, including the parameters to update for each alert. | | `alerts[].status` | string | | One of: `resolved`, `triggered`. | | `alerts[].incident` | object | | | | `alerts[].incident.id` | string | yes | | | `alerts[].incident.type` | string | | One of: `incident_reference`. | Example: Request Example ```json { "alerts": [ { "id": "PPVZH9X", "type": "alert", "status": "resolved" }, { "id": "P8JOGX7", "type": "alert", "incident": { "id": "PPVZH9X", "type": "incident_reference" } } ] } ``` ## Response 200 All of the updates succeeded. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `alerts` | array of object | yes | | | `alerts[].id` | string | | Read-only. | | `alerts[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].type` | string | yes | The type of object being created. One of: `alert`. Default: `alert`. | | `alerts[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].created_at` | string (date-time) | | The date/time the alert was first triggered. Read-only. | | `alerts[].status` | string | | The current status of the alert. One of: `triggered`, `resolved`. | | `alerts[].alert_key` | string | | The alert's de-duplication key. Read-only. | | `alerts[].service` | object | | | | `alerts[].service.id` | string | yes | Read-only. | | `alerts[].service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].service.type` | string | yes | One of: `service_reference`. | | `alerts[].service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].first_trigger_log_entry` | object | | | | `alerts[].first_trigger_log_entry.id` | string | yes | Read-only. | | `alerts[].first_trigger_log_entry.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].first_trigger_log_entry.type` | string | yes | One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `alerts[].first_trigger_log_entry.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].first_trigger_log_entry.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].incident` | object | | | | `alerts[].incident.id` | string | yes | Read-only. | | `alerts[].incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].incident.type` | string | yes | One of: `incident_reference`. | | `alerts[].incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].suppressed` | boolean | | Whether or not an alert is suppressed. Suppressed alerts are not created with a parent incident. Read-only. Default: `false`. | | `alerts[].severity` | string | | The magnitude of the problem as reported by the monitoring tool. Read-only. One of: `info`, `warning`, `error`, `critical`. | | `alerts[].integration` | object | | | | `alerts[].integration.id` | string | yes | Read-only. | | `alerts[].integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `alerts[].integration.type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `alerts[].integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `alerts[].integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `alerts[].body` | object | | A JSON object containing data describing the alert. Read-only. | | `alerts[].body.type` | string | | The type of the body. One of: `alert_body`. | | `alerts[].body.contexts` | array of object | | Contexts to be included with the body such as links to graphs or images. Read-only. | | `alerts[].body.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `alerts[].body.contexts[].href` | string | | The link's target url. | | `alerts[].body.contexts[].src` | string | | The image's source url. | | `alerts[].body.contexts[].text` | string | | The alternate display for an image. | | `alerts[].body.details` | object | | An arbitrary JSON object or string containing any data explaining the nature of the alert. Read-only. | Example: Response Example ```json { "alerts": [ { "id": "PT4KHLK", "type": "alert", "summary": "The server is on fire.", "self": "https://api.pagerduty.com/incidents/PT4KHLK/alerts/PXPGF42", "html_url": "https://subdomain.pagerduty.com/alerts/PXPGF42", "created_at": "2015-10-06T21:30:42Z", "status": "resolved", "alert_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" }, "body": { "type": "alert_body", "contexts": [ { "type": "link" } ], "details": { "customKey": "Server is on fire!", "customKey2": "Other stuff!" } }, "incident": { "id": "PPVZH9X", "type": "incident_reference" }, "suppressed": false, "severity": "critical" } ], "limit": 1, "offset": 0, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 413 Caller provided a request that is too large to process. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incident-note # Update a note on an incident `PUT https://api.pagerduty.com/incidents/{id}/notes/{note_id}` Update an existing note 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](https://docs.pagerduty.com/developer/api-concepts#incidents) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `note_id` | string | yes | The id of the note. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `note` | object | yes | | | `note.content` | string | yes | The note content. | Example: Request Example ```json { "note": { "content": "Firefighters are on the scene. Update 1." } } ``` ## Response 200 The updated note. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `note` | object | yes | | | `note.id` | string | | Read-only. | | `note.user` | object | | | | `note.user.id` | string | yes | Read-only. | | `note.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `note.user.type` | string | yes | One of: `user_reference`, `bot_user_reference`. | | `note.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `note.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `note.channel` | object | | The means by which this Note was created. Has different formats depending on type. Read-only. | | `note.channel.summary` | string | yes | A string describing the source of the Note. Read-only. | | `note.channel.id` | string | | Read-only. | | `note.channel.type` | string | | A string that determines the schema of the object. Read-only. | | `note.channel.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `note.channel.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `note.content` | string | yes | The note content. | | `note.created_at` | string (date-time) | | The time at which the note was submitted. Read-only. | | `note.updated_at` | string (date-time) | | The time at which the note was last updated. Read-only. | Example: Response Example ```json { "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. Update 1.", "created_at": "2013-03-06T15:28:51-05:00", "updated_at": "2025-01-10T12:00:00-05:00" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/incidents/update-incidents # Manage incidents `PUT https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/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. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `incidents` | array of object | yes | An array of incidents, including the parameters to update. | | `incidents[].id` | string | yes | The id of the incident to update. | | `incidents[].type` | string | yes | The incident type. One of: `incident`, `incident_reference`. | | `incidents[].status` | string | | The new status of the incident. If the incident is currently resolved, setting the status to "triggered" or "acknowledged" will reopen it. When reopening an incident to the "triggered" status, it will be assigned based on the assignees or escalation_policy fields in the request, otherwise it will be assigned to the current Escalation Policy. When reopening an incident to the "acknowledged" status, it will be assigned to the current user. One of: `resolved`, `acknowledged`, `triggered`. | | `incidents[].resolution` | string | | The resolution for this incident. This field is used only when setting the incident status to resolved. The value provided here is added to the incident’s 'Resolve' log entry as a note and will not be displayed directly in the UI. | | `incidents[].title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incidents[].priority` | one of: object \| string | | The priority of the incident. Can be provided as a priority object or a string matching a priority name. If a string is provided, the highest priority with a matching name will be used. | | `incidents[].priority.id` | string | yes | (option 1) The ID of the priority. | | `incidents[].priority.name` | string | | (option 1) The user-provided short name of the priority. | | `incidents[].priority.type` | string | yes | (option 1) The type of the reference. One of: `priority`, `priority_reference`. | | `incidents[].escalation_level` | integer | | Escalate the incident to this level in the escalation policy. | | `incidents[].assignments` | array of object | | Assign the incident to these assignees. | | `incidents[].assignments[].assignee` | object | | | | `incidents[].assignments[].assignee.id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.type` | string | yes | One of: `user_reference`. | | `incidents[].assignments[].assignee.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].incident_type` | object | | | | `incidents[].incident_type.id` | string | | Read-only. | | `incidents[].incident_type.name` | string | | The name of the Incident Type. | | `incidents[].escalation_policy` | object | | | | `incidents[].escalation_policy.id` | string | yes | Read-only. | | `incidents[].escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `incidents[].escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].urgency` | string | | The urgency of the incident. One of: `high`, `low`. | | `incidents[].conference_bridge` | object | | | | `incidents[].conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incidents[].conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | Example: Request Example ```json { "incidents": [ { "id": "PT4KHLK", "type": "incident_reference", "status": "acknowledged" }, { "id": "PQMF62U", "type": "incident_reference", "priority": { "id": "P53ZZH5", "type": "priority_reference" } }, { "id": "PPVZH9X", "type": "incident_reference", "status": "resolved" }, { "id": "P8JOGX7", "type": "incident_reference", "assignments": [ { "assignee": { "id": "PXPGF42", "type": "user_reference" } } ] }, { "id": "PYJ9K7I", "type": "incident_reference", "incident_type": { "name": "major_incident" } } ] } ``` ## Response 200 All of the updates succeeded. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `incidents` | array of object | yes | | | `incidents[].id` | string | | Read-only. | | `incidents[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incidents[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].incident_number` | integer | | The number of the incident. This is unique across your account. Read-only. | | `incidents[].title` | string | | A succinct description of the nature, symptoms, cause, or effect of the incident. | | `incidents[].created_at` | string (date-time) | | The time the incident was first triggered. Read-only. | | `incidents[].updated_at` | string (date-time) | | The time the incident was last modified. | | `incidents[].status` | string | | The current status of the incident. One of: `triggered`, `acknowledged`, `resolved`. | | `incidents[].incident_key` | string | | The incident's de-duplication key. Read-only. | | `incidents[].service` | one of: object \| object | | The service the incident is on. If the `include[]=services` query parameter is provided, the full service definition will be returned. | | `incidents[].service.id` | string | yes | (option 1) Read-only. | | `incidents[].service.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.type` | string | yes | (option 1) One of: `service_reference`. | | `incidents[].service.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].service.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.id` | string | | (option 2) Read-only. | | `incidents[].service.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.type` | string | yes | (option 2) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].service.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].service.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.name` | string | | (option 2) The name of the service. | | `incidents[].service.description` | string | | (option 2) The user-provided description of the service. | | `incidents[].service.auto_resolve_timeout` | integer | | (option 2) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].service.acknowledgement_timeout` | integer | | (option 2) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].service.created_at` | string (date-time) | | (option 2) The date/time when this service was created. Read-only. | | `incidents[].service.status` | string | | (option 2) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].service.last_incident_timestamp` | string (date-time) | | (option 2) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].service.escalation_policy` | object | yes | (option 2) Same fields as `incidents[].escalation_policy` above. | | `incidents[].service.response_play` | | | (option 2) Response plays associated with this service. **Deprecated.** | | `incidents[].service.teams` | array of object | | (option 2) The set of teams associated with this service. Read-only. | | `incidents[].service.teams[].id` | string | yes | Read-only. | | `incidents[].service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.integrations` | array of object | | (option 2) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].service.integrations[].id` | string | yes | Read-only. | | `incidents[].service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.incident_urgency_rule` | object | | (option 2) | | `incidents[].service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incidents[].service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incidents[].service.incident_urgency_rule.during_support_hours` | object | | | | `incidents[].service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `incidents[].service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `incidents[].service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `incidents[].service.incident_urgency_rule.during_support_hours` above. | | `incidents[].service.support_hours` | object | | (option 2) | | `incidents[].service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `incidents[].service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `incidents[].service.support_hours.days_of_week` | array of integer | | Read-only. | | `incidents[].service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `incidents[].service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `incidents[].service.scheduled_actions` | array of object | | (option 2) An array containing scheduled actions for the service. | | `incidents[].service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].service.addons` | array of object | | (option 2) The array of Add-ons associated with this service. Read-only. | | `incidents[].service.addons[].id` | string | yes | Read-only. | | `incidents[].service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].service.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].service.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].service.alert_creation` | string | | (option 2) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].service.alert_grouping_parameters` | one of: object \| object | | (option 2) Alert Grouping Parameters. **Deprecated.** | | `incidents[].service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].service.alert_grouping` | string | | (option 2) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].service.alert_grouping_timeout` | integer | | (option 2) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].service.auto_pause_notifications_parameters` | object | | (option 2) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `incidents[].service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `incidents[].service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `incidents[].service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | | `incidents[].assignments` | array of object | | List of all assignments for this incident. This list will be empty if the `Incident.status` is `resolved`. Returns a user reference for each assignment. Full user definitions will be returned if the `include[]=assignees` query parameter is provided. | | `incidents[].assignments[].at` | string (date-time) | yes | Time at which the assignment was created. | | `incidents[].assignments[].assignee` | one of: object \| object | yes | | | `incidents[].assignments[].assignee.id` | string | yes | (option 1) Read-only. | | `incidents[].assignments[].assignee.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.type` | string | yes | (option 1) One of: `user_reference`. | | `incidents[].assignments[].assignee.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.id` | string | | (option 2) Read-only. | | `incidents[].assignments[].assignee.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].assignments[].assignee.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].assignments[].assignee.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].assignments[].assignee.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].assignments[].assignee.color` | string | | (option 2) The schedule color. | | `incidents[].assignments[].assignee.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].assignments[].assignee.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].assignments[].assignee.description` | string \| null | | (option 2) The user's bio. | | `incidents[].assignments[].assignee.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].assignments[].assignee.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].assignments[].assignee.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].assignments[].assignee.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].assignments[].assignee.teams[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].assignments[].assignee.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].assignments[].assignee.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].id` | string | yes | Read-only. | | `incidents[].assignments[].assignee.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].assignments[].assignee.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].assignments[].assignee.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].assignments[].assignee.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].assignments[].assignee.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].assigned_via` | string | | How the current incident assignments were decided. Note that `direct_assignment` incidents will not escalate up the attached `escalation_policy` Read-only. One of: `escalation_policy`, `direct_assignment`. | | `incidents[].last_status_change_at` | string (date-time) | | The time the status of the incident last changed. If the incident is not currently acknowledged or resolved, this will be the incident's `updated_at`. Read-only. | | `incidents[].resolved_at` | string (date-time) | | The time the incident became "resolved" or `null` if the incident is not resolved. | | `incidents[].first_trigger_log_entry` | one of: object \| object | | The first log entry on the incident. The log entry will be of type `TriggerLogEntry` and will represent information about how the incident was triggered. If the `include[]=first_trigger_log_entries` query parameter is provided, the full log entry definition will be returned. | | `incidents[].first_trigger_log_entry.id` | string | yes | (option 1) Read-only. | | `incidents[].first_trigger_log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.type` | string | yes | (option 1) One of: `acknowledge_log_entry_reference`, `annotate_log_entry_reference`, `assign_log_entry_reference`, `escalate_log_entry_reference`, `exhaust_escalation_path_log_entry_reference`, `notify_log_entry_reference`, `reach_trigger_limit_log_entry_reference`, `repeat_escalation_path_log_entry_reference`, `resolve_log_entry_reference`, `snooze_log_entry_reference`, `trigger_log_entry_reference`, `unacknowledge_log_entry_reference`. | | `incidents[].first_trigger_log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.id` | string | | (option 2) Read-only. | | `incidents[].first_trigger_log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.type` | string | | (option 2) One of: `trigger_log_entry`. | | `incidents[].first_trigger_log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `incidents[].first_trigger_log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `incidents[].first_trigger_log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `incidents[].first_trigger_log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `incidents[].first_trigger_log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `incidents[].first_trigger_log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `incidents[].first_trigger_log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `incidents[].first_trigger_log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `incidents[].first_trigger_log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `incidents[].first_trigger_log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `incidents[].first_trigger_log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `incidents[].first_trigger_log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `incidents[].first_trigger_log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `incidents[].first_trigger_log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `incidents[].first_trigger_log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `incidents[].first_trigger_log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `incidents[].first_trigger_log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `incidents[].first_trigger_log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `incidents[].first_trigger_log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `incidents[].first_trigger_log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `incidents[].first_trigger_log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `incidents[].first_trigger_log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `incidents[].first_trigger_log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `incidents[].first_trigger_log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `incidents[].first_trigger_log_entry.channel.type` | string | yes | type. | | `incidents[].first_trigger_log_entry.channel.user` | object | | | | `incidents[].first_trigger_log_entry.channel.team` | object | | | | `incidents[].first_trigger_log_entry.channel.notification` | object | | | | `incidents[].first_trigger_log_entry.channel.notification.id` | string | | Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `incidents[].first_trigger_log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `incidents[].first_trigger_log_entry.channel.notification.user` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].first_trigger_log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `incidents[].first_trigger_log_entry.channel.notification.status` | string | | | | `incidents[].first_trigger_log_entry.channel.notification.` | string | | | | `incidents[].first_trigger_log_entry.channel.channel` | object | | channel. | | `incidents[].first_trigger_log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].id` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].name` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].id` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].name` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].namespace` | string | | | | `incidents[].first_trigger_log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `incidents[].first_trigger_log_entry.channel.changeset.customer_schema` | object | | | | `incidents[].first_trigger_log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `incidents[].first_trigger_log_entry.agent` | object | | (option 2) | | `incidents[].first_trigger_log_entry.agent.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `incidents[].first_trigger_log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `incidents[].first_trigger_log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `incidents[].first_trigger_log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `incidents[].first_trigger_log_entry.contexts[].href` | string | | The link's target url. | | `incidents[].first_trigger_log_entry.contexts[].src` | string | | The image's source url. | | `incidents[].first_trigger_log_entry.contexts[].text` | string | | The alternate display for an image. | | `incidents[].first_trigger_log_entry.service` | object | | (option 2) | | `incidents[].first_trigger_log_entry.service.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.service.type` | string | yes | One of: `service_reference`. | | `incidents[].first_trigger_log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.incident` | object | | (option 2) | | `incidents[].first_trigger_log_entry.incident.id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `incidents[].first_trigger_log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `incidents[].first_trigger_log_entry.teams[].id` | string | yes | Read-only. | | `incidents[].first_trigger_log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].first_trigger_log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].first_trigger_log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].first_trigger_log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].first_trigger_log_entry.event_details` | object | | (option 2) Read-only. | | `incidents[].first_trigger_log_entry.event_details.description` | string | | Additional details about the event. | | `incidents[].first_trigger_log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `incidents[].alert_counts` | object | | | | `incidents[].alert_counts.triggered` | integer | | The count of triggered alerts grouped into this incident. | | `incidents[].alert_counts.resolved` | integer | | The count of resolved alerts grouped into this incident. | | `incidents[].alert_counts.all` | integer | | The total count of alerts grouped into this incident. | | `incidents[].is_mergeable` | boolean | | Whether the incident is mergeable. Only incidents that have alerts, or that are manually created can be merged. Read-only. | | `incidents[].incident_type` | object | | The incident type of the incident. | | `incidents[].incident_type.name` | string | | The name of the Incident Type. | | `incidents[].escalation_policy` | one of: object \| object | | The escalation policy attached to the service that the incident is on. If the `include[]=escalation_policies` query parameter is provided, the full escalation policy definition will be returned. | | `incidents[].escalation_policy.id` | string | yes | (option 1) Read-only. | | `incidents[].escalation_policy.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.type` | string | yes | (option 1) One of: `escalation_policy_reference`. | | `incidents[].escalation_policy.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.id` | string | | (option 2) Read-only. | | `incidents[].escalation_policy.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.type` | string | yes | (option 2) The type of object being created. One of: `escalation_policy`. Default: `escalation_policy`. | | `incidents[].escalation_policy.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.name` | string | yes | (option 2) The name of the escalation policy. | | `incidents[].escalation_policy.description` | string | | (option 2) Escalation policy description. | | `incidents[].escalation_policy.num_loops` | integer | | (option 2) The number of times the escalation policy will repeat after reaching the end of its escalation. Default: `0`. Minimum: 0. | | `incidents[].escalation_policy.on_call_handoff_notifications` | string | | (option 2) Determines how on call handoff notifications will be sent for users on the escalation policy. Defaults to "if_has_services". One of: `if_has_services`, `always`. | | `incidents[].escalation_policy.escalation_rules` | array of object | yes | (option 2) | | `incidents[].escalation_policy.escalation_rules[].id` | string | | Read-only. | | `incidents[].escalation_policy.escalation_rules[].escalation_delay_in_minutes` | integer | yes | The number of minutes before an unacknowledged incident escalates away from this rule. | | `incidents[].escalation_policy.escalation_rules[].targets` | array of object | yes | The targets an incident should be assigned to upon reaching this rule. Min items: 1. Max items: 10. | | `incidents[].escalation_policy.escalation_rules[].targets[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].type` | string | yes | One of: `user`, `schedule`, `user_reference`, `schedule_reference`, `schedule_v3_reference`. | | `incidents[].escalation_policy.escalation_rules[].targets[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.escalation_rules[].targets[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.escalation_rules[].escalation_rule_assignment_strategy` | string | | The strategy used to assign the escalation rule to an incident. One of: `round_robin`, `assign_to_everyone`. | | `incidents[].escalation_policy.services` | array of object | | (option 2) Read-only. Min length: 0. | | `incidents[].escalation_policy.services[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.services[].type` | string | yes | One of: `service_reference`. | | `incidents[].escalation_policy.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].escalation_policy.teams` | array of object | | (option 2) Team associated with the policy. Account must have the `teams` ability to use this parameter. Only one team may be associated with the policy. Min length: 0. | | `incidents[].escalation_policy.teams[].id` | string | yes | Read-only. | | `incidents[].escalation_policy.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].escalation_policy.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].escalation_policy.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].escalation_policy.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams` | array of one of: object \| object | | The teams involved in the incident’s lifecycle. If the `include[]=teams` query parameter is provided, the full team definitions will be returned. | | `incidents[].teams[].id` | string | yes | (option 1) Read-only. | | `incidents[].teams[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].teams[].type` | string | yes | (option 1) One of: `team_reference`. | | `incidents[].teams[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].teams[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams[].id` | string | | (option 2) Read-only. | | `incidents[].teams[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].teams[].type` | string | yes | (option 2) The type of object being created. One of: `team`. Default: `team`. | | `incidents[].teams[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].teams[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].teams[].name` | string | yes | (option 2) The name of the team. Max length: 100. | | `incidents[].teams[].description` | string | | (option 2) The description of the team. Max length: 1024. | | `incidents[].teams[].default_role` | string | | (option 2) The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | | `incidents[].pending_actions` | array of object | | The list of pending_actions on the incident. A pending_action object contains a type of action which can be escalate, unacknowledge, resolve or urgency_change. A pending_action object contains at, the time at which the action will take place. An urgency_change pending_action will contain to, the urgency that the incident will change to. Read-only. | | `incidents[].pending_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `incidents[].pending_actions[].at` | string (date-time) | yes | | | `incidents[].pending_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `incidents[].acknowledgements` | array of object | | List of all acknowledgements for this incident. This list will be empty if the `Incident.status` is `resolved` or `triggered`. If the `include[]=acknowledgers` query parameter is provided, the full user or service definitions will be returned for each acknowledgement entry. | | `incidents[].acknowledgements[].at` | string (date-time) | yes | Time at which the acknowledgement was created. | | `incidents[].acknowledgements[].acknowledger` | one of: object \| object \| object | yes | | | `incidents[].acknowledgements[].acknowledger.id` | string | yes | (option 1) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.id` | string | | (option 2) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].acknowledgements[].acknowledger.color` | string | | (option 2) The schedule color. | | `incidents[].acknowledgements[].acknowledger.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].acknowledgements[].acknowledger.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].acknowledgements[].acknowledger.description` | string \| null | | (option 2) The user's bio. | | `incidents[].acknowledgements[].acknowledger.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].acknowledgements[].acknowledger.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].acknowledgements[].acknowledger.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].acknowledgements[].acknowledger.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].acknowledgements[].acknowledger.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].acknowledgements[].acknowledger.id` | string | | (option 3) Read-only. | | `incidents[].acknowledgements[].acknowledger.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].acknowledgements[].acknowledger.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.name` | string | | (option 3) The name of the service. | | `incidents[].acknowledgements[].acknowledger.description` | string | | (option 3) The user-provided description of the service. | | `incidents[].acknowledgements[].acknowledger.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].acknowledgements[].acknowledger.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].acknowledgements[].acknowledger.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incidents[].acknowledgements[].acknowledger.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].acknowledgements[].acknowledger.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.escalation_policy` | object | yes | (option 3) Same fields as `incidents[].escalation_policy` above. | | `incidents[].acknowledgements[].acknowledger.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].acknowledgements[].acknowledger.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].acknowledgements[].acknowledger.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.incident_urgency_rule` | object | | (option 3) Same fields as `incidents[].service.incident_urgency_rule` above. | | `incidents[].acknowledgements[].acknowledger.support_hours` | object | | (option 3) Same fields as `incidents[].service.support_hours` above. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].acknowledgements[].acknowledger.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].acknowledgements[].acknowledger.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].id` | string | yes | Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].acknowledgements[].acknowledger.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].acknowledgements[].acknowledger.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].acknowledgements[].acknowledger.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].acknowledgements[].acknowledger.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].acknowledgements[].acknowledger.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].acknowledgements[].acknowledger.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].acknowledgements[].acknowledger.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incidents[].service.auto_pause_notifications_parameters` above. | | `incidents[].alert_grouping` | object | | Describes the alert grouping state of this incident. Will be null if the incident has no alerts. | | `incidents[].alert_grouping.grouping_type` | string | | One of: `basic`, `advanced`, `rules`. | | `incidents[].alert_grouping.started_at` | string (date-time) | | | | `incidents[].alert_grouping.ended_at` | string (date-time) | | | | `incidents[].alert_grouping.alert_grouping_active` | boolean | | | | `incidents[].last_status_change_by` | one of: object \| object \| object | | The entity that last changed the status of the incident. If the `include[]=agents` query parameter is provided, the full user/service/integration definition will be returned. | | `incidents[].last_status_change_by.id` | string | yes | (option 1) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 1) One of: `user_reference`, `service_reference`, `integration_reference`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.id` | string | | (option 2) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 2) The type of object being created. One of: `user`. Default: `user`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.name` | string | yes | (option 2) The name of the user. Max length: 100. | | `incidents[].last_status_change_by.email` | string (email) | yes | (option 2) The user's email address. Min length: 6. Max length: 100. | | `incidents[].last_status_change_by.time_zone` | string (tzinfo) | | (option 2) The preferred time zone name. If null, the account's time zone will be used. | | `incidents[].last_status_change_by.color` | string | | (option 2) The schedule color. | | `incidents[].last_status_change_by.role` | string | | (option 2) The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `incidents[].last_status_change_by.avatar_url` | string (url) | | (option 2) The URL of the user's avatar. Read-only. | | `incidents[].last_status_change_by.description` | string \| null | | (option 2) The user's bio. | | `incidents[].last_status_change_by.invitation_sent` | boolean | | (option 2) If true, the user has an outstanding invitation. Read-only. | | `incidents[].last_status_change_by.job_title` | string | | (option 2) The user's title. Max length: 100. | | `incidents[].last_status_change_by.created_via_sso` | boolean | | (option 2) If true, the user was created via Single Sign-On (SSO). Read-only. | | `incidents[].last_status_change_by.teams` | array of object | | (option 2) The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `incidents[].last_status_change_by.teams[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.contact_methods` | array of object | | (option 2) The list of contact methods for the user. Read-only. | | `incidents[].last_status_change_by.contact_methods[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `incidents[].last_status_change_by.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.notification_rules` | array of object | | (option 2) The list of notification rules for the user. Read-only. | | `incidents[].last_status_change_by.notification_rules[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `incidents[].last_status_change_by.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.http_cal_url` | string (uri) | | (option 2) iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].last_status_change_by.web_cal_url` | string (uri) | | (option 2) iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `incidents[].last_status_change_by.id` | string | | (option 3) Read-only. | | `incidents[].last_status_change_by.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.type` | string | yes | (option 3) The type of object being created. One of: `service`. Default: `service`. | | `incidents[].last_status_change_by.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.name` | string | | (option 3) The name of the service. | | `incidents[].last_status_change_by.description` | string | | (option 3) The user-provided description of the service. | | `incidents[].last_status_change_by.auto_resolve_timeout` | integer | | (option 3) Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `incidents[].last_status_change_by.acknowledgement_timeout` | integer | | (option 3) Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `incidents[].last_status_change_by.created_at` | string (date-time) | | (option 3) The date/time when this service was created. Read-only. | | `incidents[].last_status_change_by.status` | string | | (option 3) The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `incidents[].last_status_change_by.last_incident_timestamp` | string (date-time) | | (option 3) The date/time when the most recent incident was created for this service. Read-only. | | `incidents[].last_status_change_by.escalation_policy` | object | yes | (option 3) Same fields as `incidents[].escalation_policy` above. | | `incidents[].last_status_change_by.response_play` | | | (option 3) Response plays associated with this service. **Deprecated.** | | `incidents[].last_status_change_by.teams` | array of object | | (option 3) The set of teams associated with this service. Read-only. | | `incidents[].last_status_change_by.teams[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.teams[].type` | string | yes | One of: `team_reference`. | | `incidents[].last_status_change_by.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.integrations` | array of object | | (option 3) An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `incidents[].last_status_change_by.integrations[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `incidents[].last_status_change_by.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.incident_urgency_rule` | object | | (option 3) Same fields as `incidents[].service.incident_urgency_rule` above. | | `incidents[].last_status_change_by.support_hours` | object | | (option 3) Same fields as `incidents[].service.support_hours` above. | | `incidents[].last_status_change_by.scheduled_actions` | array of object | | (option 3) An array containing scheduled actions for the service. | | `incidents[].last_status_change_by.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `incidents[].last_status_change_by.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `incidents[].last_status_change_by.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `incidents[].last_status_change_by.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `incidents[].last_status_change_by.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `incidents[].last_status_change_by.addons` | array of object | | (option 3) The array of Add-ons associated with this service. Read-only. | | `incidents[].last_status_change_by.addons[].id` | string | yes | Read-only. | | `incidents[].last_status_change_by.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].last_status_change_by.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `incidents[].last_status_change_by.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].last_status_change_by.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].last_status_change_by.addons[].src` | string (url) | | The URL source of the Addon. | | `incidents[].last_status_change_by.addons[].name` | string | | The user entered name of the Addon. | | `incidents[].last_status_change_by.alert_creation` | string | | (option 3) Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `incidents[].last_status_change_by.alert_grouping_parameters` | one of: object \| object | | (option 3) Alert Grouping Parameters. **Deprecated.** | | `incidents[].last_status_change_by.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `incidents[].last_status_change_by.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `incidents[].last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `incidents[].last_status_change_by.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `incidents[].last_status_change_by.alert_grouping` | string | | (option 3) Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `incidents[].last_status_change_by.alert_grouping_timeout` | integer | | (option 3) The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `incidents[].last_status_change_by.auto_pause_notifications_parameters` | object | | (option 3) Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. Same fields as `incidents[].service.auto_pause_notifications_parameters` above. | | `incidents[].priority` | object | | | | `incidents[].priority.id` | string | | Read-only. | | `incidents[].priority.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `incidents[].priority.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `incidents[].priority.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `incidents[].priority.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `incidents[].priority.name` | string | | The user-provided short name of the priority. | | `incidents[].priority.description` | string | | The user-provided description of the priority. | | `incidents[].resolve_reason` | object | | | | `incidents[].resolve_reason.type` | string | | The reason the incident was resolved. The only reason currently supported is merge. One of: `merge_resolve_reason`. Default: `merge_resolve_reason`. | | `incidents[].resolve_reason.incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].conference_bridge` | object | | The conference bridge information attached to the incident. Only returned if the `include[]=conference_bridge` query parameter is provided. | | `incidents[].conference_bridge.conference_number` | string | | The phone number of the conference call for the conference bridge. Phone numbers should be formatted like +1 415-555-1212,,,,1234#, where a comma (,) represents a one-second wait and pound (#) completes access code input. | | `incidents[].conference_bridge.conference_url` | string (url) | | An URL for the conference bridge. This could be a link to a web conference or Slack channel. | | `incidents[].incidents_responders` | array of object | | The responders on the incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incidents[].incidents_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incidents[].incidents_responders[].user` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].incidents_responders[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].incidents_responders[].updated_at` | string | | | | `incidents[].incidents_responders[].message` | string | | The message sent with the responder request. | | `incidents[].incidents_responders[].requester` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].incidents_responders[].requested_at` | string | | | | `incidents[].incidents_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incidents[].responder_requests` | array of object | | Previous responder requests made on this incident. Only returned if the account has access to the [responder requests](https://support.pagerduty.com/docs/add-responders) feature. Read-only. | | `incidents[].responder_requests[].id` | string | | The ID of the responder request. | | `incidents[].responder_requests[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].responder_requests[].requester` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].responder_requests[].requested_at` | string | | The time the request was made. | | `incidents[].responder_requests[].message` | string | | The message sent with the responder request. | | `incidents[].responder_requests[].responder_request_targets` | array of object | | The array of targets the responder request is being sent to. | | `incidents[].responder_requests[].responder_request_targets[].type` | string | | The type of target (either a user or an escalation policy) | | `incidents[].responder_requests[].responder_request_targets[].id` | string | | The id of the user or escalation policy. | | `incidents[].responder_requests[].responder_request_targets[].summary` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders` | array of object | | An array of responders associated with the specified incident. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].state` | string | | The status of the responder being added to the incident. One of: `pending`, `joined`, `declined`, `user_cancelled`. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].user` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].incident` | object | | Same fields as `incidents[].first_trigger_log_entry.incident` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].updated_at` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].message` | string | | The message sent with the responder request. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].requester` | object | | Same fields as `incidents[].assignments[].assignee` above. | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].requested_at` | string | | | | `incidents[].responder_requests[].responder_request_targets[].incident_responders[].escalation_policy_requests` | array of string | | Names of escalation policies that this responder was requested through, if applicable. | | `incidents[].urgency` | string | | The current urgency of the incident. One of: `high`, `low`. | | `incidents[].body` | object | | The additional incident body details. Only returned if the `include[]=body` query parameter is provided. | | `incidents[].body.details` | object | | Additional incident details. | Example: Response Example ```json { "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" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 413 Caller provided a request that is too large to process. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/create-ip-allow-list # Create an IP allow list `POST https://api.pagerduty.com/ip_allow_lists` Create the account's IP allow list. Only Account Owners, Global Admins, and Account API Keys can call this endpoint. Scoped OAuth requires: `ip_allow_lists.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_list` | object | yes | An IP allow list restricts access to a PagerDuty account's subdomain to a set of IPv4 CIDR ranges. Enforcement currently applies to web and mobile application traffic. | | `ip_allow_list.id` | string | | Unique identifier for the allow list (e.g. `AGIS47HYOV6BDODBTMQKMPQPHU`). Read-only. | | `ip_allow_list.type` | string | | A string that determines the schema of the object. Read-only. One of: `ip_allow_list`. Default: `ip_allow_list`. | | `ip_allow_list.state` | string | yes | Whether the allow list is enforced for the account. When `enabled`, only requests from IPs matching one of the `cidr_entries` are permitted to access the subdomain. When `disabled`, the allow list is stored but not enforced. One of: `enabled`, `disabled`. | | `ip_allow_list.cidr_entries` | array of object | yes | The CIDR ranges that are allowed when the allow list is `enabled`. Must be non-empty when `state` is `enabled`. Max items: 100. | | `ip_allow_list.cidr_entries[].cidr` | string | yes | An IPv4 CIDR range. Each octet must be `0`-`255` and the mask must be between `1` and `32`. Pattern: `^((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)\.){3}(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)/([1-9]\|[12]\d\|3[0-2])$`. | | `ip_allow_list.cidr_entries[].description` | string \| null | | An optional human-readable description for the entry. Limited to 64 characters. Max length: 64. | Example: Create an enabled allow list ```json { "ip_allow_list": { "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" } ] } } ``` ## Response 201 IP allow list created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_list` | object | yes | An IP allow list restricts access to a PagerDuty account's subdomain to a set of IPv4 CIDR ranges. Enforcement currently applies to web and mobile application traffic. Same fields as `ip_allow_list` above. | Example: Example response ```json { "ip_allow_list": { "id": "AGIS47HYOV6BDODBTMQKMPQPHU", "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" }, { "cidr": "10.0.0.0/24", "description": "Data Center" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/delete-ip-allow-list # Delete an IP allow list `DELETE https://api.pagerduty.com/ip_allow_lists/{id}` Delete the IP allow list with the given `id`. Subsequent `GET` and `PUT` requests for the same `id` will return `404`. The list is no longer enforced once deleted. Only Account Owners, Global Admins, and Account API Keys can call this endpoint. Scoped OAuth requires: `ip_allow_lists.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 IP allow list deleted successfully. No response body. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/get-ip-allow-list # Get an IP allow list `GET https://api.pagerduty.com/ip_allow_lists/{id}` Return the IP allow list with the given `id`. Only Account Owners, Global Admins, and Account API Keys can call this endpoint. Scoped OAuth requires: `ip_allow_lists.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 IP allow list retrieved successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_list` | object | yes | An IP allow list restricts access to a PagerDuty account's subdomain to a set of IPv4 CIDR ranges. Enforcement currently applies to web and mobile application traffic. | | `ip_allow_list.id` | string | | Unique identifier for the allow list (e.g. `AGIS47HYOV6BDODBTMQKMPQPHU`). Read-only. | | `ip_allow_list.type` | string | | A string that determines the schema of the object. Read-only. One of: `ip_allow_list`. Default: `ip_allow_list`. | | `ip_allow_list.state` | string | yes | Whether the allow list is enforced for the account. When `enabled`, only requests from IPs matching one of the `cidr_entries` are permitted to access the subdomain. When `disabled`, the allow list is stored but not enforced. One of: `enabled`, `disabled`. | | `ip_allow_list.cidr_entries` | array of object | yes | The CIDR ranges that are allowed when the allow list is `enabled`. Must be non-empty when `state` is `enabled`. Max items: 100. | | `ip_allow_list.cidr_entries[].cidr` | string | yes | An IPv4 CIDR range. Each octet must be `0`-`255` and the mask must be between `1` and `32`. Pattern: `^((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)\.){3}(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)/([1-9]\|[12]\d\|3[0-2])$`. | | `ip_allow_list.cidr_entries[].description` | string \| null | | An optional human-readable description for the entry. Limited to 64 characters. Max length: 64. | Example: Example response ```json { "ip_allow_list": { "id": "AGIS47HYOV6BDODBTMQKMPQPHU", "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" }, { "cidr": "10.0.0.0/24", "description": "Data Center" } ] } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/list-ip-allow-list-audit-records # List audit records for an IP allow list `GET https://api.pagerduty.com/ip_allow_lists/{id}/audit/records` The response will include audit records with changes that are made to the given IP allow list. The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "kRm-tyP", "action": "delete", "actors": [ { "id": "P8AC329", "type": "api_key_reference" } ], "details": { "fields": [], "references": [], "resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } }, "execution_context": { "request_id": "4e8c2a1f9b3d7e6c5a8b2c9d1e4f7a3b" }, "execution_time": "2026-04-20T18:09:47.563218Z", "method": { "type": "api_token" }, "root_resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } }, { "id": "xQ4nVbS", "action": "update", "actors": [ { "id": "P8AC329", "type": "api_key_reference" } ], "details": { "fields": [ { "name": "state", "value": "enabled", "before_value": "disabled" } ], "references": [], "resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } }, "execution_context": { "request_id": "7b3a9c1d2e5f8a4b6c9d0e1f2a3b4c5d" }, "execution_time": "2026-04-16T09:51:33.207614Z", "method": { "type": "api_token" }, "root_resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } }, { "id": "Hf8-zEm", "action": "create", "actors": [ { "id": "P8AC329", "type": "api_key_reference" } ], "details": { "fields": [ { "name": "state", "value": "disabled", "before_value": null } ], "references": [ { "name": "cidr_entries", "added": [ { "id": "192.0.2.0/24", "summary": "Example Office Network", "type": "cidr_entry" } ], "removed": [] } ], "resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } }, "execution_context": { "request_id": "2c9d1e4f7a3b6c5a8b2c9d1e4f7a3b6c" }, "execution_time": "2026-04-15T14:22:18.412903Z", "method": { "type": "api_token" }, "root_resource": { "id": "B2KTPSXM5L42BFCNYJ73HRDQML", "type": "ip_allow_list_reference" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/list-ip-allow-lists # List IP allow lists `GET https://api.pagerduty.com/ip_allow_lists` Return all IP allow lists for the account. Only Account Owners, Global Admins, and Account API Keys can call this endpoint. Scoped OAuth requires: `ip_allow_lists.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 IP allow lists retrieved successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_lists` | array of object | yes | Max items: 1. | | `ip_allow_lists[].id` | string | | Unique identifier for the allow list (e.g. `AGIS47HYOV6BDODBTMQKMPQPHU`). Read-only. | | `ip_allow_lists[].type` | string | | A string that determines the schema of the object. Read-only. One of: `ip_allow_list`. Default: `ip_allow_list`. | | `ip_allow_lists[].state` | string | yes | Whether the allow list is enforced for the account. When `enabled`, only requests from IPs matching one of the `cidr_entries` are permitted to access the subdomain. When `disabled`, the allow list is stored but not enforced. One of: `enabled`, `disabled`. | | `ip_allow_lists[].cidr_entries` | array of object | yes | The CIDR ranges that are allowed when the allow list is `enabled`. Must be non-empty when `state` is `enabled`. Max items: 100. | | `ip_allow_lists[].cidr_entries[].cidr` | string | yes | An IPv4 CIDR range. Each octet must be `0`-`255` and the mask must be between `1` and `32`. Pattern: `^((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)\.){3}(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)/([1-9]\|[12]\d\|3[0-2])$`. | | `ip_allow_lists[].cidr_entries[].description` | string \| null | | An optional human-readable description for the entry. Limited to 64 characters. Max length: 64. | Example: Example response ```json { "ip_allow_lists": [ { "id": "AGIS47HYOV6BDODBTMQKMPQPHU", "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" }, { "cidr": "10.0.0.0/24", "description": "Data Center" } ] } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/ip-allow-lists/update-ip-allow-list # Update an IP allow list `PUT https://api.pagerduty.com/ip_allow_lists/{id}` Update the IP allow list with the given `id`. The request body fully replaces the writable fields. Only Account Owners, Global Admins, and Account API Keys can call this endpoint. Scoped OAuth requires: `ip_allow_lists.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_list` | object | yes | An IP allow list restricts access to a PagerDuty account's subdomain to a set of IPv4 CIDR ranges. Enforcement currently applies to web and mobile application traffic. | | `ip_allow_list.id` | string | | Unique identifier for the allow list (e.g. `AGIS47HYOV6BDODBTMQKMPQPHU`). Read-only. | | `ip_allow_list.type` | string | | A string that determines the schema of the object. Read-only. One of: `ip_allow_list`. Default: `ip_allow_list`. | | `ip_allow_list.state` | string | yes | Whether the allow list is enforced for the account. When `enabled`, only requests from IPs matching one of the `cidr_entries` are permitted to access the subdomain. When `disabled`, the allow list is stored but not enforced. One of: `enabled`, `disabled`. | | `ip_allow_list.cidr_entries` | array of object | yes | The CIDR ranges that are allowed when the allow list is `enabled`. Must be non-empty when `state` is `enabled`. Max items: 100. | | `ip_allow_list.cidr_entries[].cidr` | string | yes | An IPv4 CIDR range. Each octet must be `0`-`255` and the mask must be between `1` and `32`. Pattern: `^((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)\.){3}(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)/([1-9]\|[12]\d\|3[0-2])$`. | | `ip_allow_list.cidr_entries[].description` | string \| null | | An optional human-readable description for the entry. Limited to 64 characters. Max length: 64. | Example: Replace the allow list entries ```json { "ip_allow_list": { "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" }, { "cidr": "10.0.0.0/24", "description": "Data Center" } ] } } ``` ## Response 200 IP allow list updated successfully. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ip_allow_list` | object | yes | An IP allow list restricts access to a PagerDuty account's subdomain to a set of IPv4 CIDR ranges. Enforcement currently applies to web and mobile application traffic. Same fields as `ip_allow_list` above. | Example: Example response ```json { "ip_allow_list": { "id": "AGIS47HYOV6BDODBTMQKMPQPHU", "type": "ip_allow_list", "state": "enabled", "cidr_entries": [ { "cidr": "192.168.1.0/24", "description": "Office VPN" }, { "cidr": "10.0.0.0/24", "description": "Data Center" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/licenses/list-license-allocations # List License Allocations `GET https://api.pagerduty.com/license_allocations` List the Licenses allocated to Users within your Account Scoped OAuth requires: `licenses.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 License allocations to Users within your Account ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `license_allocations` | array of object | | | | `license_allocations[].user` | object | yes | | | `license_allocations[].user.id` | string | yes | Read-only. | | `license_allocations[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `license_allocations[].user.type` | string | yes | One of: `user_reference`. | | `license_allocations[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `license_allocations[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `license_allocations[].license` | object | yes | | | `license_allocations[].license.id` | string | yes | Uniquely identifies the resource. | | `license_allocations[].license.description` | string | yes | Description of the License. May include the names of add-ons associated with the License, if there are any. | | `license_allocations[].license.name` | string | yes | Name of the License. | | `license_allocations[].license.valid_roles` | array of string | yes | The roles a User with this License can have. | | `license_allocations[].license.role_group` | string | | Indicates whether this License is assignable to full or stakeholder Users. One of: `FullUser`, `Stakeholder`. | | `license_allocations[].license.type` | string | | Type of object. | | `license_allocations[].license.self` | string | | API URL to access the License. | | `license_allocations[].license.html_url` | string | | HTML URL to access the License. | | `license_allocations[].license.summary` | string | | Summary of the License. | | `license_allocations[].allocated_at` | string (date-time) | yes | Indicates the date and time the License was allocated to the User. | | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | Example: Response Example ```json { "license_allocations": [ { "license": { "id": "PIP248G", "name": "Business (Full User)", "description": "Event Intelligence", "valid_roles": [ "owner", "admin", "user", "limited_user", "observer", "restricted_access" ], "role_group": "FullUser", "summary": "Business (Full User)", "type": "license", "self": null, "html_url": null }, "user": { "id": "PIP248H", "type": "user_reference" }, "allocated_at": "2021-06-01T00:00:00-05:00" } ], "offset": 0, "limit": 1, "more": false, "total": 2 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/licenses/list-licenses # List Licenses `GET https://api.pagerduty.com/licenses` List the Licenses associated with your Account Scoped OAuth requires: `licenses.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Licenses associated with your Account ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `licenses` | array of object | | | | `licenses[].id` | string | yes | Uniquely identifies the resource. | | `licenses[].description` | string | yes | Description of the License. May include the names of add-ons associated with the License, if there are any. | | `licenses[].name` | string | yes | Name of the License. | | `licenses[].valid_roles` | array of string | yes | The roles a User with this License can have. | | `licenses[].role_group` | string | | Indicates whether this License is assignable to full or stakeholder Users. One of: `FullUser`, `Stakeholder`. | | `licenses[].type` | string | | Type of object. | | `licenses[].self` | string | | API URL to access the License. | | `licenses[].html_url` | string | | HTML URL to access the License. | | `licenses[].summary` | string | | Summary of the License. | | `licenses[].current_value` | integer | | How many of these Licenses are currently allocated to Users. | | `licenses[].allocations_available` | integer \| null | | How many of these licenses are available to be allocated to a user. If this value is "null" then there is no limit on the number of allocations allowed. | Example: Example Response ```json { "licenses": [ { "id": "PIP248G", "name": "Business (Full User)", "description": "Event Intelligence", "current_value": 234, "allocations_available": 4766, "valid_roles": [ "owner", "admin", "user", "limited_user", "observer", "restricted_access" ], "role_group": "FullUser", "summary": "Business (Full User)", "type": "license", "self": null, "html_url": null }, { "id": "PTHH1SQ", "name": "Business (Full User)", "description": "", "current_value": 0, "allocations_available": 4766, "valid_roles": [ "owner", "admin", "user", "limited_user", "observer", "restricted_access" ], "role_group": "FullUser", "summary": "Business (Full User)", "type": "license", "self": null, "html_url": null }, { "id": "PQ8W0D0", "name": "Business (Stakeholder)", "description": "", "current_value": 48, "allocations_available": 4952, "valid_roles": [ "read_only_user", "read_only_limited_user" ], "role_group": "Stakeholder", "summary": "Business (Stakeholder)", "type": "license", "self": null, "html_url": null } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/log-entries/get-log-entry # Get a log entry `GET https://api.pagerduty.com/log_entries/{id}` Get details for a specific incident log entry. This method provides additional information you can use to get at raw event data. A log of all the events that happen to an Incident, and these are exposed as Log Entries. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#log-entries) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `include[]` | string | | Array of additional Models to include in response. One of: `incidents`, `services`, `channels`, `teams`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A single log entry. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `log_entry` | one of: object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object | yes | | | `log_entry.id` | string | | (option 1) Read-only. | | `log_entry.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 1) One of: `acknowledgement_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 1) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 1) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `log_entry.channel.type` | string | | (NagiosChannel) Will be `nagios` | | `log_entry.channel.summary` | string | | (NagiosChannel) Same as `host` | | `log_entry.channel.host` | string | | (NagiosChannel) Nagios host. | | `log_entry.channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `log_entry.channel.state` | string | | (NagiosChannel) State that caused the event. | | `log_entry.channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `log_entry.channel.type` | string | | (APIChannel) Will be `api` | | `log_entry.channel.summary` | string | | (APIChannel) Same as `description` | | `log_entry.channel.service_key` | string | | (APIChannel) API service key. | | `log_entry.channel.description` | string | | (APIChannel) Description of the event. | | `log_entry.channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `log_entry.channel.details` | object | | (APIChannel) Additional details of the incident. | | `log_entry.channel.type` | string | | (EmailChannel) Will be `email` | | `log_entry.channel.summary` | string | | (EmailChannel) Same as `subject` | | `log_entry.channel.to` | string | | (EmailChannel) To address of the email. | | `log_entry.channel.from` | string | | (EmailChannel) From address of the email. | | `log_entry.channel.subject` | string | | (EmailChannel) Subject of the email. | | `log_entry.channel.body` | string | | (EmailChannel) Body of the email. | | `log_entry.channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `log_entry.channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `log_entry.channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `log_entry.channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `log_entry.channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `log_entry.channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `log_entry.channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `log_entry.channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `log_entry.channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `log_entry.channel.type` | string | yes | type. | | `log_entry.channel.user` | object | | | | `log_entry.channel.team` | object | | | | `log_entry.channel.notification` | object | | | | `log_entry.channel.notification.id` | string | | Read-only. | | `log_entry.channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `log_entry.channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `log_entry.channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `log_entry.channel.notification.user` | object | | | | `log_entry.channel.notification.user.id` | string | yes | Read-only. | | `log_entry.channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.channel.notification.user.type` | string | yes | One of: `user_reference`. | | `log_entry.channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `log_entry.channel.notification.status` | string | | | | `log_entry.channel.notification.` | string | | | | `log_entry.channel.channel` | object | | channel. | | `log_entry.channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entry.channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entry.channel.changeset.customer_fields[].id` | string | | | | `log_entry.channel.changeset.customer_fields[].name` | string | | | | `log_entry.channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `log_entry.channel.changeset.customer_fields[].namespace` | string | | | | `log_entry.channel.changeset.customer_fields[].old_value` | string \| null | | | | `log_entry.channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entry.channel.changeset.application_fields[].id` | string | | | | `log_entry.channel.changeset.application_fields[].name` | string | | | | `log_entry.channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `log_entry.channel.changeset.application_fields[].namespace` | string | | | | `log_entry.channel.changeset.application_fields[].old_value` | string \| null | | | | `log_entry.channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `log_entry.channel.changeset.customer_schema` | object | | | | `log_entry.channel.changeset.customer_schema.old_value` | string \| null | | | | `log_entry.agent` | object | | (option 1) | | `log_entry.agent.id` | string | yes | Read-only. | | `log_entry.agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `log_entry.agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.note` | string | | (option 1) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 1) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 1) | | `log_entry.service.id` | string | yes | Read-only. | | `log_entry.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.service.type` | string | yes | One of: `service_reference`. | | `log_entry.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.incident` | object | | (option 1) | | `log_entry.incident.id` | string | yes | Read-only. | | `log_entry.incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.incident.type` | string | yes | One of: `incident_reference`. | | `log_entry.incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.teams` | array of object | | (option 1) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 1) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 1) String record of custom field updates. | | `log_entry.acknowledgement_timeout` | integer | | (option 1) Duration for which the acknowledgement lasts, in seconds. Services can contain an `acknowledgement_timeout` property, which specifies the length of time acknowledgements should last for. Each time an incident is acknowledged, this timeout is copied into the acknowledgement log entry. This property is optional, as older log entries may not contain it. It may also be `null`, as acknowledgements can be performed on incidents whose services have no `acknowledgement_timeout` set. | | `log_entry.id` | string | | (option 2) Read-only. | | `log_entry.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 2) One of: `annotate_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 2) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 2) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 2) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 2) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 2) String record of custom field updates. | | `log_entry.id` | string | | (option 3) Read-only. | | `log_entry.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 3) One of: `assign_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 3) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 3) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 3) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 3) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 3) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 3) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 3) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 3) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 3) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 3) String record of custom field updates. | | `log_entry.assignees` | array of object | | (option 3) An array of assigned Users for this log entry. Read-only. | | `log_entry.assignees[].id` | string | yes | Read-only. | | `log_entry.assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.assignees[].type` | string | yes | One of: `user_reference`. | | `log_entry.assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.id` | string | | (option 4) Read-only. | | `log_entry.summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 4) One of: `delegate_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 4) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 4) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 4) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 4) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 4) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 4) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 4) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 4) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 4) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 4) String record of custom field updates. | | `log_entry.assignees` | array of object | | (option 4) An array of assigned Users for this log entry. Read-only. | | `log_entry.assignees[].id` | string | yes | Read-only. | | `log_entry.assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.assignees[].type` | string | yes | One of: `user_reference`. | | `log_entry.assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.id` | string | | (option 5) Read-only. | | `log_entry.summary` | string \| null | | (option 5) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 5) One of: `escalate_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 5) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 5) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 5) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 5) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 5) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 5) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 5) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 5) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 5) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 5) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 5) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 5) String record of custom field updates. | | `log_entry.assignees` | array of object | | (option 5) An array of assigned Users for this log entry. Read-only. | | `log_entry.assignees[].id` | string | yes | Read-only. | | `log_entry.assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.assignees[].type` | string | yes | One of: `user_reference`. | | `log_entry.assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.id` | string | | (option 6) Read-only. | | `log_entry.summary` | string \| null | | (option 6) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 6) One of: `exhaust_escalation_path_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 6) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 6) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 6) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 6) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 6) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 6) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 6) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 6) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 6) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 6) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 6) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 6) String record of custom field updates. | | `log_entry.id` | string | | (option 7) Read-only. | | `log_entry.summary` | string \| null | | (option 7) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 7) One of: `notify_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 7) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 7) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 7) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 7) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 7) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 7) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 7) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 7) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 7) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 7) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 7) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 7) String record of custom field updates. | | `log_entry.user` | object | | (option 7) Same fields as `log_entry.channel.notification.user` above. | | `log_entry.id` | string | | (option 8) Read-only. | | `log_entry.summary` | string \| null | | (option 8) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 8) One of: `reach_ack_limit_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 8) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 8) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 8) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 8) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 8) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 8) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 8) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 8) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 8) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 8) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 8) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 8) String record of custom field updates. | | `log_entry.id` | string | | (option 9) Read-only. | | `log_entry.summary` | string \| null | | (option 9) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 9) One of: `reach_trigger_limit_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 9) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 9) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 9) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 9) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 9) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 9) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 9) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 9) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 9) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 9) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 9) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 9) String record of custom field updates. | | `log_entry.id` | string | | (option 10) Read-only. | | `log_entry.summary` | string \| null | | (option 10) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 10) One of: `repeat_escalation_path_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 10) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 10) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 10) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 10) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 10) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 10) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 10) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 10) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 10) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 10) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 10) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 10) String record of custom field updates. | | `log_entry.id` | string | | (option 11) Read-only. | | `log_entry.summary` | string \| null | | (option 11) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 11) One of: `resolve_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 11) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 11) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 11) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 11) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 11) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 11) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 11) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 11) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 11) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 11) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 11) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 11) String record of custom field updates. | | `log_entry.id` | string | | (option 12) Read-only. | | `log_entry.summary` | string \| null | | (option 12) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 12) One of: `snooze_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 12) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 12) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 12) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 12) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 12) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 12) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 12) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 12) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 12) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 12) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 12) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 12) String record of custom field updates. | | `log_entry.changed_actions` | array of object | | (option 12) | | `log_entry.changed_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `log_entry.changed_actions[].at` | string (date-time) | yes | | | `log_entry.changed_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `log_entry.id` | string | | (option 13) Read-only. | | `log_entry.summary` | string \| null | | (option 13) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 13) One of: `trigger_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 13) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 13) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 13) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 13) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 13) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 13) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 13) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 13) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 13) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 13) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 13) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 13) String record of custom field updates. | | `log_entry.id` | string | | (option 14) Read-only. | | `log_entry.summary` | string \| null | | (option 14) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 14) One of: `unacknowledge_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 14) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 14) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 14) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 14) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 14) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 14) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 14) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 14) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 14) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 14) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 14) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 14) String record of custom field updates. | | `log_entry.id` | string | | (option 15) Read-only. | | `log_entry.summary` | string \| null | | (option 15) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.type` | string | | (option 15) One of: `urgency_change_log_entry`. | | `log_entry.self` | string \| null (url) | | (option 15) the API show URL at which the object is accessible. Read-only. | | `log_entry.html_url` | string \| null (url) | | (option 15) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.created_at` | string (date-time) | | (option 15) Time at which the log entry was created. Read-only. | | `log_entry.channel` | one of: object \| object \| object \| object \| object | | (option 15) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entry.channel` above. | | `log_entry.agent` | object | | (option 15) Same fields as `log_entry.agent` above. | | `log_entry.note` | string | | (option 15) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entry.contexts` | array of object | | (option 15) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entry.contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entry.contexts[].href` | string | | The link's target url. | | `log_entry.contexts[].src` | string | | The image's source url. | | `log_entry.contexts[].text` | string | | The alternate display for an image. | | `log_entry.service` | object | | (option 15) Same fields as `log_entry.service` above. | | `log_entry.incident` | object | | (option 15) Same fields as `log_entry.incident` above. | | `log_entry.teams` | array of object | | (option 15) Will consist of references unless included. Read-only. | | `log_entry.teams[].id` | string | yes | Read-only. | | `log_entry.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entry.teams[].type` | string | yes | One of: `team_reference`. | | `log_entry.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entry.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entry.event_details` | object | | (option 15) Read-only. | | `log_entry.event_details.description` | string | | Additional details about the event. | | `log_entry.changeset` | array of string | | (option 15) String record of custom field updates. | Example: Response Example ```json { "log_entry": { "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" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/log-entries/list-log-entries # List log entries `GET https://api.pagerduty.com/log_entries` List all of the incident log entries across the entire account. A log of all the events that happen to an Incident, and these are exposed as Log Entries. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#log-entries) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | | `is_overview` | boolean | | If `true`, will return a subset of log entries that show only the most important changes to the incident. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `incidents`, `services`, `channels`, `teams`. Items must be unique. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of log entries. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `log_entries` | array of one of: object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object | yes | | | `log_entries[].id` | string | | (option 1) Read-only. | | `log_entries[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 1) One of: `acknowledgement_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 1) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 1) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. | | `log_entries[].channel.type` | string | | (NagiosChannel) Will be `nagios` | | `log_entries[].channel.summary` | string | | (NagiosChannel) Same as `host` | | `log_entries[].channel.host` | string | | (NagiosChannel) Nagios host. | | `log_entries[].channel.service` | string | | (NagiosChannel) Nagios service that created the event, if applicable. | | `log_entries[].channel.state` | string | | (NagiosChannel) State that caused the event. | | `log_entries[].channel.details` | object | | (NagiosChannel) Additional details of the incident. | | `log_entries[].channel.type` | string | | (APIChannel) Will be `api` | | `log_entries[].channel.summary` | string | | (APIChannel) Same as `description` | | `log_entries[].channel.service_key` | string | | (APIChannel) API service key. | | `log_entries[].channel.description` | string | | (APIChannel) Description of the event. | | `log_entries[].channel.incident_key` | string | | (APIChannel) Incident deduping string. | | `log_entries[].channel.details` | object | | (APIChannel) Additional details of the incident. | | `log_entries[].channel.type` | string | | (EmailChannel) Will be `email` | | `log_entries[].channel.summary` | string | | (EmailChannel) Same as `subject` | | `log_entries[].channel.to` | string | | (EmailChannel) To address of the email. | | `log_entries[].channel.from` | string | | (EmailChannel) From address of the email. | | `log_entries[].channel.subject` | string | | (EmailChannel) Subject of the email. | | `log_entries[].channel.body` | string | | (EmailChannel) Body of the email. | | `log_entries[].channel.body_content_type` | string | | (EmailChannel) Content type of the email body. Will be `text/plain` or `text/html` | | `log_entries[].channel.raw_url` | string | | (EmailChannel) URL for raw text of email. | | `log_entries[].channel.html_url` | string | | (EmailChannel) URL for html rendered version of the email. Only present if `content_type` is `text/html` | | `log_entries[].channel.type` | string | | (WebTriggerChannel) Will be `web_trigger` | | `log_entries[].channel.summary` | string | | (WebTriggerChannel) Same as `subject` | | `log_entries[].channel.subject` | string | | (WebTriggerChannel) Subject of the web trigger. | | `log_entries[].channel.details` | string | | (WebTriggerChannel) Details about the web trigger. | | `log_entries[].channel.type` | string | yes | (WebsiteChannel) Will be `website` | | `log_entries[].channel.duration` | integer | | (WebsiteChannel) For `snooze` log entries, this is the number of seconds that the incident was snoozed for. | | `log_entries[].channel.type` | string | yes | type. | | `log_entries[].channel.user` | object | | | | `log_entries[].channel.team` | object | | | | `log_entries[].channel.notification` | object | | | | `log_entries[].channel.notification.id` | string | | Read-only. | | `log_entries[].channel.notification.type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `log_entries[].channel.notification.started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `log_entries[].channel.notification.address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `log_entries[].channel.notification.user` | object | | | | `log_entries[].channel.notification.user.id` | string | yes | Read-only. | | `log_entries[].channel.notification.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].channel.notification.user.type` | string | yes | One of: `user_reference`. | | `log_entries[].channel.notification.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].channel.notification.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].channel.notification.conferenceAddress` | string | | The address of the conference bridge. | | `log_entries[].channel.notification.status` | string | | | | `log_entries[].channel.notification.` | string | | | | `log_entries[].channel.channel` | object | | channel. | | `log_entries[].channel.changeset` | object | | Changeset present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.customer_fields` | array of object | | Customer Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.customer_fields[].id` | string | | | | `log_entries[].channel.changeset.customer_fields[].name` | string | | | | `log_entries[].channel.changeset.customer_fields[].value` | one of: integer \| array of string | | | | `log_entries[].channel.changeset.customer_fields[].namespace` | string | | | | `log_entries[].channel.changeset.customer_fields[].old_value` | string \| null | | | | `log_entries[].channel.changeset.application_fields` | array of object | | Application Fields present in CustomFieldsValueChange and FieldValueChange log entries. | | `log_entries[].channel.changeset.application_fields[].id` | string | | | | `log_entries[].channel.changeset.application_fields[].name` | string | | | | `log_entries[].channel.changeset.application_fields[].value` | one of: string \| integer \| array of string | | | | `log_entries[].channel.changeset.application_fields[].namespace` | string | | | | `log_entries[].channel.changeset.application_fields[].old_value` | string \| null | | | | `log_entries[].channel.changeset.custom_attributes` | object | | Custom attributes for the changeset. | | `log_entries[].channel.changeset.customer_schema` | object | | | | `log_entries[].channel.changeset.customer_schema.old_value` | string \| null | | | | `log_entries[].agent` | object | | (option 1) | | `log_entries[].agent.id` | string | yes | Read-only. | | `log_entries[].agent.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].agent.type` | string | yes | One of: `user_reference`, `service_reference`, `integration_reference`. | | `log_entries[].agent.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].agent.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].note` | string | | (option 1) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 1) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 1) | | `log_entries[].service.id` | string | yes | Read-only. | | `log_entries[].service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].service.type` | string | yes | One of: `service_reference`. | | `log_entries[].service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].incident` | object | | (option 1) | | `log_entries[].incident.id` | string | yes | Read-only. | | `log_entries[].incident.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].incident.type` | string | yes | One of: `incident_reference`. | | `log_entries[].incident.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].incident.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].teams` | array of object | | (option 1) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 1) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 1) String record of custom field updates. | | `log_entries[].acknowledgement_timeout` | integer | | (option 1) Duration for which the acknowledgement lasts, in seconds. Services can contain an `acknowledgement_timeout` property, which specifies the length of time acknowledgements should last for. Each time an incident is acknowledged, this timeout is copied into the acknowledgement log entry. This property is optional, as older log entries may not contain it. It may also be `null`, as acknowledgements can be performed on incidents whose services have no `acknowledgement_timeout` set. | | `log_entries[].id` | string | | (option 2) Read-only. | | `log_entries[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 2) One of: `annotate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 2) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 2) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 2) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 2) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 2) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 2) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 2) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 2) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 2) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 2) String record of custom field updates. | | `log_entries[].id` | string | | (option 3) Read-only. | | `log_entries[].summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 3) One of: `assign_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 3) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 3) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 3) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 3) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 3) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 3) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 3) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 3) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 3) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 3) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 3) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 4) Read-only. | | `log_entries[].summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 4) One of: `delegate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 4) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 4) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 4) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 4) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 4) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 4) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 4) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 4) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 4) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 4) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 4) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 5) Read-only. | | `log_entries[].summary` | string \| null | | (option 5) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 5) One of: `escalate_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 5) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 5) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 5) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 5) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 5) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 5) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 5) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 5) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 5) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 5) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 5) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 5) String record of custom field updates. | | `log_entries[].assignees` | array of object | | (option 5) An array of assigned Users for this log entry. Read-only. | | `log_entries[].assignees[].id` | string | yes | Read-only. | | `log_entries[].assignees[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].assignees[].type` | string | yes | One of: `user_reference`. | | `log_entries[].assignees[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].assignees[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].id` | string | | (option 6) Read-only. | | `log_entries[].summary` | string \| null | | (option 6) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 6) One of: `exhaust_escalation_path_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 6) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 6) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 6) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 6) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 6) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 6) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 6) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 6) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 6) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 6) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 6) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 6) String record of custom field updates. | | `log_entries[].id` | string | | (option 7) Read-only. | | `log_entries[].summary` | string \| null | | (option 7) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 7) One of: `notify_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 7) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 7) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 7) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 7) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 7) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 7) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 7) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 7) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 7) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 7) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 7) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 7) String record of custom field updates. | | `log_entries[].user` | object | | (option 7) Same fields as `log_entries[].channel.notification.user` above. | | `log_entries[].id` | string | | (option 8) Read-only. | | `log_entries[].summary` | string \| null | | (option 8) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 8) One of: `reach_ack_limit_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 8) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 8) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 8) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 8) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 8) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 8) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 8) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 8) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 8) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 8) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 8) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 8) String record of custom field updates. | | `log_entries[].id` | string | | (option 9) Read-only. | | `log_entries[].summary` | string \| null | | (option 9) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 9) One of: `reach_trigger_limit_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 9) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 9) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 9) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 9) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 9) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 9) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 9) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 9) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 9) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 9) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 9) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 9) String record of custom field updates. | | `log_entries[].id` | string | | (option 10) Read-only. | | `log_entries[].summary` | string \| null | | (option 10) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 10) One of: `repeat_escalation_path_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 10) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 10) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 10) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 10) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 10) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 10) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 10) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 10) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 10) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 10) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 10) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 10) String record of custom field updates. | | `log_entries[].id` | string | | (option 11) Read-only. | | `log_entries[].summary` | string \| null | | (option 11) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 11) One of: `resolve_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 11) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 11) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 11) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 11) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 11) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 11) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 11) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 11) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 11) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 11) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 11) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 11) String record of custom field updates. | | `log_entries[].id` | string | | (option 12) Read-only. | | `log_entries[].summary` | string \| null | | (option 12) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 12) One of: `snooze_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 12) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 12) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 12) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 12) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 12) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 12) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 12) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 12) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 12) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 12) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 12) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 12) String record of custom field updates. | | `log_entries[].changed_actions` | array of object | | (option 12) | | `log_entries[].changed_actions[].type` | string | yes | One of: `unacknowledge`, `escalate`, `resolve`, `urgency_change`. | | `log_entries[].changed_actions[].at` | string (date-time) | yes | | | `log_entries[].changed_actions[].to` | string | | The urgency that the incident will change to. This field is only present when the type is `urgency_change`. One of: `high`. | | `log_entries[].id` | string | | (option 13) Read-only. | | `log_entries[].summary` | string \| null | | (option 13) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 13) One of: `trigger_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 13) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 13) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 13) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 13) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 13) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 13) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 13) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 13) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 13) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 13) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 13) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 13) String record of custom field updates. | | `log_entries[].id` | string | | (option 14) Read-only. | | `log_entries[].summary` | string \| null | | (option 14) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 14) One of: `unacknowledge_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 14) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 14) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 14) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 14) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 14) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 14) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 14) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 14) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 14) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 14) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 14) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 14) String record of custom field updates. | | `log_entries[].id` | string | | (option 15) Read-only. | | `log_entries[].summary` | string \| null | | (option 15) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].type` | string | | (option 15) One of: `urgency_change_log_entry`. | | `log_entries[].self` | string \| null (url) | | (option 15) the API show URL at which the object is accessible. Read-only. | | `log_entries[].html_url` | string \| null (url) | | (option 15) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].created_at` | string (date-time) | | (option 15) Time at which the log entry was created. Read-only. | | `log_entries[].channel` | one of: object \| object \| object \| object \| object | | (option 15) Polymorphic object representation of the means by which the action was channeled. Has different formats depending on type, indicated by channel[type]. Will be one of `auto`, `email`, `api`, `nagios`, or `timeout` if `agent[type]` is `service`. Will be one of `email`, `sms`, `website`, `web_trigger`, or `note` if `agent[type]` is `user`. Same fields as `log_entries[].channel` above. | | `log_entries[].agent` | object | | (option 15) Same fields as `log_entries[].agent` above. | | `log_entries[].note` | string | | (option 15) Optional field containing a note, if one was included with the log entry. Read-only. | | `log_entries[].contexts` | array of object | | (option 15) Contexts to be included with the trigger such as links to graphs or images. Read-only. | | `log_entries[].contexts[].type` | string | yes | The type of context being attached to the incident. One of: `link`, `image`. | | `log_entries[].contexts[].href` | string | | The link's target url. | | `log_entries[].contexts[].src` | string | | The image's source url. | | `log_entries[].contexts[].text` | string | | The alternate display for an image. | | `log_entries[].service` | object | | (option 15) Same fields as `log_entries[].service` above. | | `log_entries[].incident` | object | | (option 15) Same fields as `log_entries[].incident` above. | | `log_entries[].teams` | array of object | | (option 15) Will consist of references unless included. Read-only. | | `log_entries[].teams[].id` | string | yes | Read-only. | | `log_entries[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `log_entries[].teams[].type` | string | yes | One of: `team_reference`. | | `log_entries[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `log_entries[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `log_entries[].event_details` | object | | (option 15) Read-only. | | `log_entries[].event_details.description` | string | | Additional details about the event. | | `log_entries[].changeset` | array of string | | (option 15) String record of custom field updates. | Example: Response Example ```json { "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" } } ], "limit": 1, "offset": 0, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/log-entries/update-log-entry-channel # Update log entry channel information. `PUT https://api.pagerduty.com/log_entries/{id}/channel` Update an existing incident log entry channel. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#log-entries) Scoped OAuth requires: `incidents.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) The log entry channel to be updated. | Field | Type | Required | Description | |---|---|---|---| | `channel` | object | yes | The parameters to update. | | `channel.details` | string | yes | New channel details. | | `channel.type` | string | yes | Channel type. Cannot be changed and must match the present value. One of: `web_trigger`, `mobile`. | Example: Request Example ```json { "channel": { "type": "web_trigger", "details": "New channel details" } } ``` ## Response 202 The channel information modification was accepted. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/maintenance-windows/create-maintenance-window # Create a maintenance window `POST https://api.pagerduty.com/maintenance_windows` Create a new maintenance window for the specified services. No new incidents will be created for a service that is in maintenance. A Maintenance Window is used to temporarily disable one or more Services for a set period of time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#maintenance-windows) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) The maintenance window object. | Field | Type | Required | Description | |---|---|---|---| | `maintenance_window` | object | yes | | | `maintenance_window.id` | string | | Read-only. | | `maintenance_window.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.type` | string | yes | The type of object being created. One of: `maintenance_window`. Default: `maintenance_window`. | | `maintenance_window.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.sequence_number` | integer | | The order in which the maintenance window was created. Read-only. | | `maintenance_window.start_time` | string (date-time) | yes | This maintenance window's start time. This is when the services will stop creating incidents. If this date is in the past, it will be updated to be the current time. | | `maintenance_window.end_time` | string (date-time) | yes | This maintenance window's end time. This is when the services will start creating incidents again. This date must be in the future and after the `start_time`. | | `maintenance_window.description` | string | | A description for this maintenance window. | | `maintenance_window.created_by` | object | | | | `maintenance_window.created_by.id` | string | yes | Read-only. | | `maintenance_window.created_by.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.created_by.type` | string | yes | One of: `user_reference`. | | `maintenance_window.created_by.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.created_by.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.services` | array of object | yes | | | `maintenance_window.services[].id` | string | yes | Read-only. | | `maintenance_window.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.services[].type` | string | yes | One of: `service_reference`. | | `maintenance_window.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.teams` | array of object | | Read-only. | | `maintenance_window.teams[].id` | string | yes | Read-only. | | `maintenance_window.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.teams[].type` | string | yes | One of: `team_reference`. | | `maintenance_window.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "maintenance_window": { "type": "maintenance_window", "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "services": [ { "id": "PIJ90N7", "type": "service_reference" } ] } } ``` ## Response 201 The maintenance window that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `maintenance_window` | object | yes | Same fields as `maintenance_window` above. | Example: Response Example ```json { "maintenance_window": { "id": "PW98YIO", "type": "maintenance_window", "summary": "Immanentizing the eschaton", "self": "https://api.pagerduty.com/maintenance_windows/PW98YIO", "html_url": "https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO", "sequence_number": 1, "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "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" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8" } ], "created_by": { "id": "PXPGF42", "type": "user_reference", "summary": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/maintenance-windows/delete-maintenance-window # Delete or end a maintenance window `DELETE https://api.pagerduty.com/maintenance_windows/{id}` Delete an existing maintenance window if it's in the future, or end it if it's currently on-going. If the maintenance window has already ended it cannot be deleted. A Maintenance Window is used to temporarily disable one or more Services for a set period of time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#maintenance-windows) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The maintenance window was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The maintenance window can't be deleted because it has already ended. ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/maintenance-windows/get-maintenance-window # Get a maintenance window `GET https://api.pagerduty.com/maintenance_windows/{id}` Get an existing maintenance window. A Maintenance Window is used to temporarily disable one or more Services for a set period of time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#maintenance-windows) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. One of: `teams`, `services`, `users`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The maintenance window that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `maintenance_window` | object | yes | | | `maintenance_window.id` | string | | Read-only. | | `maintenance_window.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.type` | string | yes | The type of object being created. One of: `maintenance_window`. Default: `maintenance_window`. | | `maintenance_window.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.sequence_number` | integer | | The order in which the maintenance window was created. Read-only. | | `maintenance_window.start_time` | string (date-time) | yes | This maintenance window's start time. This is when the services will stop creating incidents. If this date is in the past, it will be updated to be the current time. | | `maintenance_window.end_time` | string (date-time) | yes | This maintenance window's end time. This is when the services will start creating incidents again. This date must be in the future and after the `start_time`. | | `maintenance_window.description` | string | | A description for this maintenance window. | | `maintenance_window.created_by` | object | | | | `maintenance_window.created_by.id` | string | yes | Read-only. | | `maintenance_window.created_by.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.created_by.type` | string | yes | One of: `user_reference`. | | `maintenance_window.created_by.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.created_by.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.services` | array of object | yes | | | `maintenance_window.services[].id` | string | yes | Read-only. | | `maintenance_window.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.services[].type` | string | yes | One of: `service_reference`. | | `maintenance_window.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.teams` | array of object | | Read-only. | | `maintenance_window.teams[].id` | string | yes | Read-only. | | `maintenance_window.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.teams[].type` | string | yes | One of: `team_reference`. | | `maintenance_window.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "maintenance_window": { "id": "PW98YIO", "type": "maintenance_window", "summary": "Immanentizing the eschaton", "self": "https://api.pagerduty.com/maintenance_windows/PW98YIO", "html_url": "https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO", "sequence_number": 1, "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "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" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8" } ], "created_by": { "id": "PXPGF42", "type": "user_reference", "summary": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/maintenance-windows/list-maintenance-windows # List maintenance windows `GET https://api.pagerduty.com/maintenance_windows` List existing maintenance windows, optionally filtered by service and/or team, or whether they are from the past, present or future. A Maintenance Window is used to temporarily disable one or more Services for a set period of time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#maintenance-windows) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `service_ids[]` | array of string | | An array of service IDs. Only results related to these services will be returned. | | `include[]` | string | | Array of additional Models to include in response. One of: `teams`, `services`, `users`. Items must be unique. | | `filter` | string | | Only return maintenance windows in a given state. One of: `past`, `future`, `ongoing`, `open`, `all`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of maintenance windows. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `maintenance_windows` | array of object | yes | | | `maintenance_windows[].id` | string | | Read-only. | | `maintenance_windows[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_windows[].type` | string | yes | The type of object being created. One of: `maintenance_window`. Default: `maintenance_window`. | | `maintenance_windows[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_windows[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_windows[].sequence_number` | integer | | The order in which the maintenance window was created. Read-only. | | `maintenance_windows[].start_time` | string (date-time) | yes | This maintenance window's start time. This is when the services will stop creating incidents. If this date is in the past, it will be updated to be the current time. | | `maintenance_windows[].end_time` | string (date-time) | yes | This maintenance window's end time. This is when the services will start creating incidents again. This date must be in the future and after the `start_time`. | | `maintenance_windows[].description` | string | | A description for this maintenance window. | | `maintenance_windows[].created_by` | object | | | | `maintenance_windows[].created_by.id` | string | yes | Read-only. | | `maintenance_windows[].created_by.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_windows[].created_by.type` | string | yes | One of: `user_reference`. | | `maintenance_windows[].created_by.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_windows[].created_by.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_windows[].services` | array of object | yes | | | `maintenance_windows[].services[].id` | string | yes | Read-only. | | `maintenance_windows[].services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_windows[].services[].type` | string | yes | One of: `service_reference`. | | `maintenance_windows[].services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_windows[].services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_windows[].teams` | array of object | | Read-only. | | `maintenance_windows[].teams[].id` | string | yes | Read-only. | | `maintenance_windows[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_windows[].teams[].type` | string | yes | One of: `team_reference`. | | `maintenance_windows[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_windows[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "maintenance_windows": [ { "id": "PW98YIO", "type": "maintenance_window", "summary": "Immanentizing the eschaton", "self": "https://api.pagerduty.com/maintenance_windows/PW98YIO", "html_url": "https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO", "sequence_number": 1, "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "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" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8" } ], "created_by": { "id": "PXPGF42", "type": "user_reference", "summary": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" } } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/maintenance-windows/update-maintenance-window # Update a maintenance window `PUT https://api.pagerduty.com/maintenance_windows/{id}` Update an existing maintenance window. A Maintenance Window is used to temporarily disable one or more Services for a set period of time. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#maintenance-windows) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The maintenance window to be updated. | Field | Type | Required | Description | |---|---|---|---| | `maintenance_window` | object | yes | | | `maintenance_window.id` | string | | Read-only. | | `maintenance_window.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.type` | string | yes | The type of object being created. One of: `maintenance_window`. Default: `maintenance_window`. | | `maintenance_window.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.sequence_number` | integer | | The order in which the maintenance window was created. Read-only. | | `maintenance_window.start_time` | string (date-time) | yes | This maintenance window's start time. This is when the services will stop creating incidents. If this date is in the past, it will be updated to be the current time. | | `maintenance_window.end_time` | string (date-time) | yes | This maintenance window's end time. This is when the services will start creating incidents again. This date must be in the future and after the `start_time`. | | `maintenance_window.description` | string | | A description for this maintenance window. | | `maintenance_window.created_by` | object | | | | `maintenance_window.created_by.id` | string | yes | Read-only. | | `maintenance_window.created_by.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.created_by.type` | string | yes | One of: `user_reference`. | | `maintenance_window.created_by.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.created_by.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.services` | array of object | yes | | | `maintenance_window.services[].id` | string | yes | Read-only. | | `maintenance_window.services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.services[].type` | string | yes | One of: `service_reference`. | | `maintenance_window.services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `maintenance_window.teams` | array of object | | Read-only. | | `maintenance_window.teams[].id` | string | yes | Read-only. | | `maintenance_window.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `maintenance_window.teams[].type` | string | yes | One of: `team_reference`. | | `maintenance_window.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `maintenance_window.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "maintenance_window": { "type": "maintenance_window", "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "services": [ { "id": "PIJ90N7", "type": "service_reference" } ] } } ``` ## Response 200 The maintenance window that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `maintenance_window` | object | yes | Same fields as `maintenance_window` above. | Example: Response Example ```json { "maintenance_window": { "id": "PW98YIO", "type": "maintenance_window", "summary": "Immanentizing the eschaton", "self": "https://api.pagerduty.com/maintenance_windows/PW98YIO", "html_url": "https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO", "sequence_number": 1, "start_time": "2015-11-09T20:00:00-05:00", "end_time": "2015-11-09T22:00:00-05:00", "description": "Immanentizing the eschaton", "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" } ], "teams": [ { "id": "PQ9K7I8", "type": "team_reference", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8" } ], "created_by": { "id": "PXPGF42", "type": "user_reference", "summary": "Earline Greenholt", "self": "https://api.pagerduty.com/users/PXPGF42", "html_url": "https://subdomain.pagerduty.com/users/PXPGF42" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/notifications/list-notifications # List notifications `GET https://api.pagerduty.com/notifications` List notifications for a given time range, optionally filtered by type (sms_notification, email_notification, phone_notification, or push_notification). A Notification is created when an Incident is triggered or escalated. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#notifications) Scoped OAuth requires: `users:notifications.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `since` | string (date-time) | yes | The start of the date range over which you want to search. The time element is optional. | | `until` | string (date-time) | yes | The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months. | | `filter` | string | | Return notification of this type only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `include[]` | string | | Array of additional details to include. One of: `users`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of notifications. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `notifications` | array of object | yes | | | `notifications[].id` | string | | Read-only. | | `notifications[].type` | string | | The type of notification. Read-only. One of: `sms_notification`, `email_notification`, `phone_notification`, `push_notification`. | | `notifications[].started_at` | string (date-time) | | The time at which the notification was sent. Read-only. | | `notifications[].address` | string | | The address where the notification was sent. This will be null for notification type `push_notification`. Read-only. | | `notifications[].user` | object | | | | `notifications[].user.id` | string | yes | Read-only. | | `notifications[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notifications[].user.type` | string | yes | One of: `user_reference`. | | `notifications[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notifications[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notifications[].conferenceAddress` | string | | The address of the conference bridge. | | `notifications[].status` | string | | | | `notifications[].` | string | | | Example: Response Example ```json { "notifications": [ { "id": "PWL7QXS", "type": "phone_notification", "started_at": "2013-03-06T15:28:51-05:00", "address": "+15555551234", "user": { "id": "PT23IWX", "type": "user_reference", "summary": "Tim Wright", "self": "https://api.pagerduty.com/users/PT23IWX", "html_url": "https://subdomain.pagerduty.com/users/PT23IWX" } }, { "id": "PKN7NBH", "type": "push_notification", "started_at": "2013-03-06T15:28:51-05:00", "user": { "id": "PT23IWX", "type": "user_reference", "summary": "Tim Wright", "self": "https://api.pagerduty.com/users/PT23IWX", "html_url": "https://subdomain.pagerduty.com/users/PT23IWX" } } ], "limit": 100, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/oauth-delegations/delete-oauth-delegations # Delete all OAuth delegations `DELETE https://api.pagerduty.com/oauth_delegations` Delete all OAuth delegations as per provided query parameters. An OAuth delegation represents an instance of a user or account's authorization to an app (via OAuth) to access their PagerDuty account. Common apps include the PagerDuty mobile app, Slack, Microsoft Teams, and third-party apps. It also represents a user session in the PagerDuty web app. Deleting an OAuth delegation will revoke that instance of an app's access to that user or account. To grant access again, reauthorization/reauthentication will be required. This endpoint supports deleting mobile app OAuth delegations for a given user, which is equivalent to signing users out of the mobile app. It also supports deleting delegations of type web, which is equivalent to signing users out of the web app. This is a synchronous API. Scoped OAuth requires: `oauth_delegations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `user_id` | string | yes | The ID of the user for whom this request is applicable. | | `type` | string | yes | The type of OAuth delegations this request should target. Allowed values are 'mobile' (to sign users out of the mobile app) and 'web' (to sign users out of the web app). You can pass one or more types in, separated by commas (e.g., `type=web,mobile`). One of: `mobile`, `web`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The request to delete delegations has been processed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | | Example: Response Example ```json { "status": "ok" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/oauth-delegations/get-oauth-delegations-revocation-requests-status # Get OAuth delegations revocation requests status `GET https://api.pagerduty.com/oauth_delegations/revocation_requests/status` **Deprecated.** > ### Deprecated > This endpoint is deprecated as OAuth token revocation is now synchronous. Please use the [DELETE /oauth_delegations endpoint](https://docs.pagerduty.com/developer/api/reference/rest/oauth-delegations/delete-oauth-delegations) instead. Get the status of all OAuth delegations revocation requests for this account, specifically how many requests are still pending. As all requests are now synchronous, no pending requests will be found. This endpoint is limited to account owners and admins. Scoped OAuth requires: `oauth_delegations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `requested_at_end` | string (date-time) | | The end of the date range over which you want to search. If not specified, this will default to current time. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/on-calls/list-on-calls # List all of the on-calls `GET https://api.pagerduty.com/oncalls` 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](https://docs.pagerduty.com/developer/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. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `include[]` | string | | Array of additional details to include. One of: `escalation_policies`, `users`, `schedules`. Items must be unique. | | `user_ids[]` | array of string | | Filters the results, showing only on-calls for the specified user IDs. Items must be unique. | | `escalation_policy_ids[]` | array of string | | Filters the results, showing only on-calls for the specified escalation policy IDs. Items must be unique. | | `schedule_ids[]` | array of string | | 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. Items must be unique. | | `since` | string (date-time) | | 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. | | `until` | string (date-time) | | 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. | | `earliest` | boolean | | 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. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of on-call objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `oncalls` | array of object | yes | | | `oncalls[].escalation_policy` | object | | | | `oncalls[].escalation_policy.id` | string | yes | Read-only. | | `oncalls[].escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncalls[].escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `oncalls[].escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncalls[].escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `oncalls[].user` | object | | | | `oncalls[].user.id` | string | yes | Read-only. | | `oncalls[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncalls[].user.type` | string | yes | One of: `user_reference`. | | `oncalls[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncalls[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `oncalls[].schedule` | one of: object \| object | | The schedule from which this on-call originates. May be a legacy schedule reference or a v3 schedule reference. | | `oncalls[].schedule.id` | string | yes | (option 1) Read-only. | | `oncalls[].schedule.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncalls[].schedule.type` | string | yes | (option 1) One of: `schedule_reference`. | | `oncalls[].schedule.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `oncalls[].schedule.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `oncalls[].schedule.id` | string | yes | (option 2) | | `oncalls[].schedule.type` | string | yes | (option 2) One of: `schedule_v3_reference`. | | `oncalls[].schedule.summary` | string | yes | (option 2) Schedule name. | | `oncalls[].schedule.self` | string (uri) | | (option 2) | | `oncalls[].schedule.html_url` | string (uri) | | (option 2) | | `oncalls[].escalation_level` | integer | | The escalation level for the on-call. Read-only. | | `oncalls[].start` | string (date-time) | | The start of the on-call. If `null`, the on-call is a permanent user on-call. Read-only. | | `oncalls[].end` | string (date-time) | | The end of the on-call. If `null`, the user does not go off-call. Read-only. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/paused-incident-reports/get-paused-incident-report-alerts # Get Paused Incident Reporting on Alerts `GET https://api.pagerduty.com/paused_incident_reports/alerts` Returns the 5 most recent alerts that were triggered after being paused and the 5 most recent alerts that were resolved after being paused for a given reporting period (maximum 6 months lookback period). Note: This feature is currently available as part of the Event Intelligence package or Digital Operations plan only. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#paused-incident-reports) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | | `service_id` | string | | Specifies a filter to limit the scope of reporting to a particular service. | | `suspended_by` | | | Specifies a filter to scope the response to either alerts suspended by Auto Pause or Event Rules. One of: `auto_pause`, `rules`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Paused Incident Reporting on Alerts for the Account or scoped to a Service. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `paused_incident_reporting_alerts` | object | | A list of the 5 most recent paused Alerts that weere triggered and 5 most recent Alerts that were reesolved before being triggerd. | | `paused_incident_reporting_alerts.since` | string | | The start of the date range over which the report data is represented. | | `paused_incident_reporting_alerts.until` | string | | The end of the date range over which the report data is represented. | | `paused_incident_reporting_alerts.triggered_after_pause_alerts` | array of object | | An array of Alerts that were triggered after being paused. | | `paused_incident_reporting_alerts.triggered_after_pause_alerts[].id` | string | | The Alert ID. | | `paused_incident_reporting_alerts.triggered_after_pause_alerts[].service_id` | string | | The Alert's Service ID. | | `paused_incident_reporting_alerts.triggered_after_pause_alerts[].created_at` | string | | The date/time the Alert was created. | | `paused_incident_reporting_alerts.resolved_after_pause_alerts` | array of object | | An array of Alerts that were resolved after being paused. | | `paused_incident_reporting_alerts.resolved_after_pause_alerts[].id` | string | | The Alert ID. | | `paused_incident_reporting_alerts.resolved_after_pause_alerts[].service_id` | string | | The Alert's Service ID. | | `paused_incident_reporting_alerts.resolved_after_pause_alerts[].created_at` | string | | The date/time the Alert was created. | Example: Response Example ```json { "paused_incident_reporting_counts": { "since": "2021-06-01TT13:08:14Z", "until": "2021-08-01T13:08:14Z", "triggered_after_pause_alerts": [ { "id": "PR2P3RW", "service_id": "PPSCXAN", "created_at": "2020-10-18T12:01:11Z" } ], "resolved_after_pause_alerts": [ { "id": "PS2R1RZ", "service_id": "PRS12XW", "created_at": "2020-10-17T02:02:10Z" }, { "id": "PS1S1SX", "service_id": "PRS12XW", "created_at": "2020-10-16T15:02:19Z" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/paused-incident-reports/get-paused-incident-report-counts # Get Paused Incident Reporting counts `GET https://api.pagerduty.com/paused_incident_reports/counts` Returns reporting counts for paused Incident usage for a given reporting period (maximum 6 months lookback period). Note: This feature is currently available as part of the Event Intelligence package or Digital Operations plan only. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#paused-incident-reports) Scoped OAuth requires: `incidents.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | | `service_id` | string | | Specifies a filter to limit the scope of reporting to a particular service. | | `suspended_by` | | | Specifies a filter to scope the response to either alerts suspended by Auto Pause or Event Rules. One of: `auto_pause`, `rules`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Paused Incident Reporting counts for the Account or scoped to a Service. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `paused_incident_reporting_counts` | object | | A representation of Alerts that were paused, triggered after pause, and resolved after pause. | | `paused_incident_reporting_counts.since` | string | | The start of the date range over which the report data is represented. | | `paused_incident_reporting_counts.until` | string | | The end of the date range over which the report data is represented. | | `paused_incident_reporting_counts.paused_count` | number | | The total number of paused Alerts for the Account or Servce. | | `paused_incident_reporting_counts.triggered_after_pause_count` | number | | The total number of paused Alerts for the Account or Service that were triggerd after being paused (non-transient Alerts). | | `paused_incident_reporting_counts.resolved_after_pause_count` | number | | The total number of paused Alerts for the Account or Service that were resolved after being paused and not triggered (transient Alerts). | Example: Response Example ```json { "paused_incident_reporting_counts": { "since": "2021-06-01TT13:08:14Z", "until": "2021-08-01T13:08:14Z", "paused_count": 50, "triggered_after_pause_count": 12, "resolved_after_pause_count": 38 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/priorities/list-priorities # List priorities `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#priorities) Scoped OAuth requires: `priorities.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of priorities. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `priorities` | array of object | yes | | | `priorities[].id` | string | | Read-only. | | `priorities[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `priorities[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `priorities[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `priorities[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `priorities[].name` | string | | The user-provided short name of the priority. | | `priorities[].description` | string | | The user-provided description of the priority. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/recommendations/accept-recommended-rule # Accept a recommended rule `POST https://api.pagerduty.com/recommendations/event_orchestrations/services/{service_id}/rules/{recommendation_id}/accept` Accept a recommended rule and apply it to the service's Event Orchestration. Scoped OAuth requires: `recommendations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `recommendation_id` | string | yes | The recommendation ID (rule instance hash). | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Successful response confirming the action was applied. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | One of: `ok`. | Example: Response Example ```json { "status": "ok" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/recommendations/delete-accepted-recommended-rule # Delete an accepted rule `DELETE https://api.pagerduty.com/recommendations/event_orchestrations/services/{service_id}/accepted_rules/{rule_id}` Remove a previously accepted recommended rule from a service's Event Orchestration. Scoped OAuth requires: `recommendations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `rule_id` | string | yes | The ID of the accepted rule. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Successful response confirming the action was applied. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | One of: `ok`. | Example: Response Example ```json { "status": "ok" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/recommendations/dismiss-recommended-rule # Dismiss a recommended rule `POST https://api.pagerduty.com/recommendations/event_orchestrations/services/{service_id}/rules/{recommendation_id}/dismiss` Dismiss a recommended rule for a service, recording feedback on whether the recommendation was useful. Scoped OAuth requires: `recommendations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | yes | The service ID. | | `recommendation_id` | string | yes | The recommendation ID (rule instance hash). | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required A request to dismiss a recommended rule with feedback. | Field | Type | Required | Description | |---|---|---|---| | `decision` | object | yes | | | `decision.feedback` | string | yes | Feedback on whether the recommendation was useful. - `positive`: The recommendation was relevant and useful. - `negative`: The recommendation was not relevant or not useful. One of: `positive`, `negative`. | Example: Request Example: Dismiss with negative feedback ```json { "decision": { "feedback": "negative" } } ``` Example: Request Example: Dismiss with positive feedback ```json { "decision": { "feedback": "positive" } } ``` ## Response 200 Successful response confirming the action was applied. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | string | | One of: `ok`. | Example: Response Example ```json { "status": "ok" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/recommendations/list-recommended-rules # List recommended rules `GET https://api.pagerduty.com/recommendations/event_orchestrations/rules` List AI-generated recommended rules available for an account's Service Event Orchestrations. Results can be filtered by service or team. Use cursor-based pagination to retrieve large result sets. Note: `service_id` and `service_ids[]` cannot be used together in the same request. Scoped OAuth requires: `recommendations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `service_id` | string | | Filter recommended rules for a single service. Cannot be combined with `service_ids[]`. | | `service_ids[]` | array of string | | Filter recommended rules for multiple services. Cannot be combined with `service_id`. Items must be unique. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `actions[]` | array of string | | Filter recommended rules by action type. Items must be unique. | | `limit` | integer | | The number of results per page. Default: `25`. Minimum: 1. Maximum: 50. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of recommended rules for the account's Service Event Orchestrations. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `recommended_rules` | array of object | | | | `recommended_rules[].recommendation_id` | string | | The unique identifier for this recommendation (rule instance hash). Read-only. | | `recommended_rules[].type` | string | | The type of resource this recommendation applies to. Read-only. One of: `service`. | | `recommended_rules[].status` | string | | The availability status of the recommendation. Read-only. One of: `available`. | | `recommended_rules[].description` | string | | A human-readable description of what the recommended rule does. | | `recommended_rules[].pcl_expr` | string | | The PagerDuty Condition Language (PCL) expression that defines the rule's matching condition. | | `recommended_rules[].created_at` | string (date-time) | | The date/time the recommendation was created. Read-only. | | `recommended_rules[].updated_at` | string (date-time) | | The date/time the recommendation was last updated. Read-only. | | `recommended_rules[].metrics` | object | | Performance metrics describing the recommendation's historical match rate and effectiveness. Read-only. | | `recommended_rules[].metrics.num_events_matching_rule` | integer | | Total number of events that match the rule's condition. | | `recommended_rules[].metrics.num_events_with_action` | integer | | Total number of events that had the recommended action applied. | | `recommended_rules[].metrics.num_events_with_action_matching_rule` | integer | | Number of events that both match the condition and had the action applied. | | `recommended_rules[].metrics.precision_metric` | number (float) | | Fraction of events matching the rule that also had the action applied. Value between 0 and 1. Minimum: 0. Maximum: 1. | | `recommended_rules[].metrics.recall` | number (float) | | Fraction of events with the action applied that also match the rule condition. Value between 0 and 1. Minimum: 0. Maximum: 1. | | `recommended_rules[].actions` | object | | The action the recommended rule would apply when its condition is matched. One of the following action types will be present. | | `recommended_rules[].actions.suppress` | boolean | | If true, matching events will be suppressed. | | `recommended_rules[].actions.severity` | string | | Normalize the severity of matching events to this value. One of: `critical`, `high`, `warning`, `info`, `low`. | | `recommended_rules[].actions.priority` | string | | The ID of the priority to assign to matching incidents. | | `recommended_rules[].parent` | object | | The service this recommendation applies to. Read-only. | | `recommended_rules[].parent.id` | string | | The obfuscated ID of the service. | | `recommended_rules[].parent.type` | string | | The type of the parent resource. One of: `service_reference`. | | `next_cursor` | string \| null | | Cursor to retrieve the next page of results. Null if there are no more results. | Example: Response Example ```json { "recommended_rules": [ { "recommendation_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "type": "service", "status": "available", "description": "Suppress alerts where event.summary matches 'disk usage'", "pcl_expr": "event.summary matches part 'disk usage'", "created_at": "2026-01-15T10:30:00Z", "updated_at": "2026-01-15T10:30:00Z", "metrics": { "num_events_matching_rule": 1200, "num_events_with_action": 950, "num_events_with_action_matching_rule": 900, "precision_metric": 0.75, "recall": 0.95 }, "actions": { "suppress": true }, "parent": { "id": "P1ABC23", "type": "service_reference" } } ], "next_cursor": "eyJ2ZXJzaW9uIjoxLCJwYWdlIjoyLCJuZXh0X3JlY29tbWVuZGF0aW9uIjpudWxsfQ==" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/create-ruleset # Create a Ruleset `POST https://api.pagerduty.com/rulesets` Create a new Ruleset. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `ruleset` | object | yes | | | `ruleset.id` | string | | ID of the Ruleset. Read-only. | | `ruleset.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `ruleset.type` | string | | Read-only. One of: `global`, `default_global`. | | `ruleset.name` | string | yes | Name of the Ruleset. | | `ruleset.routing_keys` | array of string | | Routing keys routed to this Ruleset. Read-only. | | `ruleset.created_at` | string (date-time) | | The date the Ruleset was created at. Read-only. | | `ruleset.creator` | object | | Reference to the user that has created the Ruleset. Read-only. | | `ruleset.creator.id` | string | | Read-only. | | `ruleset.creator.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.creator.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.updated_at` | string (date-time) | | The date the Ruleset was last updated. Read-only. | | `ruleset.updater` | object | | Reference to the user that has updated the Ruleset last. Read-only. | | `ruleset.updater.id` | string | | Read-only. | | `ruleset.updater.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.updater.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.team` | object | | Reference to the team that owns the Ruleset. If none is specified, only admins have access. | | `ruleset.team.id` | string | yes | | | `ruleset.team.type` | string | yes | A string that determines the schema of the object. Read-only. | | `ruleset.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Request Example ```json { "ruleset": { "name": "MySQL Clusters", "team": { "id": "PWL7QXS", "type": "team_reference" } } } ``` ## Response 201 The Ruleset that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ruleset` | object | | | | `ruleset.id` | string | | ID of the Ruleset. Read-only. | | `ruleset.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `ruleset.type` | string | | Read-only. One of: `global`, `default_global`. | | `ruleset.name` | string | | Name of the Ruleset. | | `ruleset.routing_keys` | array of string | | Routing keys routed to this Ruleset. Read-only. | | `ruleset.created_at` | string (date-time) | | The date the Ruleset was created at. Read-only. | | `ruleset.creator` | object | | Reference to the user that has created the Ruleset. Read-only. | | `ruleset.creator.id` | string | | Read-only. | | `ruleset.creator.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.creator.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.updated_at` | string (date-time) | | The date the Ruleset was last updated. Read-only. | | `ruleset.updater` | object | | Reference to the user that has updated the Ruleset last. Read-only. | | `ruleset.updater.id` | string | | Read-only. | | `ruleset.updater.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.updater.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.team` | object | | Reference to the team that owns the Ruleset. If none is specified, only admins have access. | | `ruleset.team.id` | string | yes | | | `ruleset.team.type` | string | yes | A string that determines the schema of the object. Read-only. | | `ruleset.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "rulesets": { "id": "0e84de00-9511-4380-9f4f-a7b568bb49a0", "name": "MySQL Clusters", "type": "global", "routing_keys": [ "R0212P1QXGEIQE2NMTQ7L7WXD00DWHIN" ], "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0", "created_at": "2019-12-24T21:18:52Z", "creator": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "updated_at": "2019-12-25T14:54:23Z", "updater": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "team": { "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF", "id": "P3ZQXDF" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/create-ruleset-event-rule # Create an Event Rule `POST https://api.pagerduty.com/rulesets/{id}/rules` Create a new Event Rule. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Note: Create and Update on rules will accept 'description' or 'summary' interchangeably as an extraction action target. Get and List on rules will always return 'summary' as the target. If you are expecting 'description' please change your automation code to expect 'summary' instead. Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule in the Ruleset. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching rule is found. | | `rule.catch_all` | boolean | | Indicates whether the Event Rule is the last Event Rule of the Ruleset that serves as a catch-all. It has limited functionality compared to other rules and always matches. Read-only. | | `rule.actions` | object | | When an event matches this rule, the actions that will be taken to change the resulting alert and incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | | `rule.actions.route` | object \| null | | Set the service ID of the target service for the resulting alert. You can find the service you want to route to by calling the services endpoint. | | `rule.actions.route.value` | string | yes | The target service's ID. | Example: Request Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "catch_all": false, "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "details.host" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was created by a Global Event Rule" }, "route": { "value": "PI2KBWI" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 201 The Event Rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | Same fields as `rule` above. | Example: Response Example ```json { "ruleset": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "catch_all": false, "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "details.host" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was created by a Global Event Rule" }, "route": { "value": "PI2KBWI" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/delete-ruleset # Delete a Ruleset `DELETE https://api.pagerduty.com/rulesets/{id}` Delete a Ruleset. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Ruleset was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/delete-ruleset-event-rule # Delete an Event Rule `DELETE https://api.pagerduty.com/rulesets/{id}/rules/{rule_id}` Delete an Event Rule. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Event Rule was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/get-ruleset # Get a Ruleset `GET https://api.pagerduty.com/rulesets/{id}` Get a Ruleset. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Ruleset object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ruleset` | object | | | | `ruleset.id` | string | | ID of the Ruleset. Read-only. | | `ruleset.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `ruleset.type` | string | | Read-only. One of: `global`, `default_global`. | | `ruleset.name` | string | | Name of the Ruleset. | | `ruleset.routing_keys` | array of string | | Routing keys routed to this Ruleset. Read-only. | | `ruleset.created_at` | string (date-time) | | The date the Ruleset was created at. Read-only. | | `ruleset.creator` | object | | Reference to the user that has created the Ruleset. Read-only. | | `ruleset.creator.id` | string | | Read-only. | | `ruleset.creator.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.creator.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.updated_at` | string (date-time) | | The date the Ruleset was last updated. Read-only. | | `ruleset.updater` | object | | Reference to the user that has updated the Ruleset last. Read-only. | | `ruleset.updater.id` | string | | Read-only. | | `ruleset.updater.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.updater.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.team` | object | | Reference to the team that owns the Ruleset. If none is specified, only admins have access. | | `ruleset.team.id` | string | yes | | | `ruleset.team.type` | string | yes | A string that determines the schema of the object. Read-only. | | `ruleset.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "ruleset": { "id": "0e84de00-9511-4380-9f4f-a7b568bb49a0", "name": "MySQL Clusters", "type": "global", "routing_keys": [ "R0212P1QXGEIQE2NMTQ7L7WXD00DWHIN" ], "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0", "created_at": "2019-12-24T21:18:52Z", "creator": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "updated_at": "2019-12-25T14:54:23Z", "updater": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "team": { "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF", "id": "P3ZQXDF" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/get-ruleset-event-rule # Get an Event Rule `GET https://api.pagerduty.com/rulesets/{id}/rules/{rule_id}` Get an Event Rule. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Note: Create and Update on rules will accept 'description' or 'summary' interchangeably as an extraction action target. Get and List on rules will always return 'summary' as the target. If you are expecting 'description' please change your automation code to expect 'summary' instead. Scoped OAuth requires: `event_rules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Event Rule object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule in the Ruleset. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching rule is found. | | `rule.catch_all` | boolean | | Indicates whether the Event Rule is the last Event Rule of the Ruleset that serves as a catch-all. It has limited functionality compared to other rules and always matches. Read-only. | | `rule.actions` | object | | When an event matches this rule, the actions that will be taken to change the resulting alert and incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | | `rule.actions.route` | object \| null | | Set the service ID of the target service for the resulting alert. You can find the service you want to route to by calling the services endpoint. | | `rule.actions.route.value` | string | yes | The target service's ID. | Example: Response Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "catch_all": false, "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "details.host" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was created by a Global Event Rule" }, "route": { "value": "PI2KBWI" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "template": "{{error_level}} error on host {{host}}" } ] }, "variables": [ { "name": "error_level", "type": "regex", "parameters": { "value": ".*error level is (\\w+)\\.", "path": "payload.summary" } }, { "name": "host", "type": "regex", "parameters": { "value": "(.*)-USW2", "path": "payload.host.human_name" } } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/list-ruleset-event-rules # List Event Rules `GET https://api.pagerduty.com/rulesets/{id}/rules` List all Event Rules on a Ruleset. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Note: Create and Update on rules will accept 'description' or 'summary' interchangeably as an extraction action target. Get and List on rules will always return 'summary' as the target. If you are expecting 'description' please change your automation code to expect 'summary' instead. Scoped OAuth requires: `event_rules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Event Rule objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `rules` | array of object | | The paginated list of rules of the Ruleset. | | `rules[].id` | string | | ID of the Event Rule. Read-only. | | `rules[].self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rules[].disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rules[].conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rules[].conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rules[].conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rules[].conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rules[].conditions.subconditions[].parameters` | object | yes | | | `rules[].conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rules[].conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rules[].conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rules[].time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rules[].time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rules[].time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rules[].time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rules[].time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rules[].time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rules[].time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rules[].time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rules[].time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rules[].variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rules[].variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rules[].variables[].name` | string | yes | The name of the variable. | | `rules[].variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rules[].variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rules[].variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rules[].position` | integer | | Position/index of the Event Rule in the Ruleset. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching rule is found. | | `rules[].catch_all` | boolean | | Indicates whether the Event Rule is the last Event Rule of the Ruleset that serves as a catch-all. It has limited functionality compared to other rules and always matches. Read-only. | | `rules[].actions` | object | | When an event matches this rule, the actions that will be taken to change the resulting alert and incident. | | `rules[].actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rules[].actions.annotate.value` | string | yes | The content of the note. | | `rules[].actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rules[].actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rules[].actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rules[].actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rules[].actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rules[].actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rules[].actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rules[].actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rules[].actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rules[].actions.priority.value` | string | yes | The priority ID. | | `rules[].actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rules[].actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rules[].actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rules[].actions.suppress.value` | boolean | yes | | | `rules[].actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rules[].actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rules[].actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rules[].actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rules[].actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | | `rules[].actions.route` | object \| null | | Set the service ID of the target service for the resulting alert. You can find the service you want to route to by calling the services endpoint. | | `rules[].actions.route.value` | string | yes | The target service's ID. | Example: Response Example ```json { "rules": [ { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "catch_all": false, "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "details.host" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was created by a Global Event Rule" }, "route": { "value": "PI2KBWI" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } }, { "id": "0d819a5a-b714-4bae-9333-dc73ea0daefb", "position": 1, "disabled": false, "catch_all": true, "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/0d819a5a-b714-4bae-9333-dc73ea0daefb", "actions": { "suppress": { "value": true }, "severity": null, "route": null, "priority": null, "extractions": [], "event_action": null, "annotate": null } } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/list-rulesets # List Rulesets `GET https://api.pagerduty.com/rulesets` List all Rulesets > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Ruleset objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `rulesets` | array of object | | | | `rulesets[].id` | string | | ID of the Ruleset. Read-only. | | `rulesets[].self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rulesets[].type` | string | | Read-only. One of: `global`, `default_global`. | | `rulesets[].name` | string | | Name of the Ruleset. | | `rulesets[].routing_keys` | array of string | | Routing keys routed to this Ruleset. Read-only. | | `rulesets[].created_at` | string (date-time) | | The date the Ruleset was created at. Read-only. | | `rulesets[].creator` | object | | Reference to the user that has created the Ruleset. Read-only. | | `rulesets[].creator.id` | string | | Read-only. | | `rulesets[].creator.type` | string | | A string that determines the schema of the object. Read-only. | | `rulesets[].creator.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `rulesets[].updated_at` | string (date-time) | | The date the Ruleset was last updated. Read-only. | | `rulesets[].updater` | object | | Reference to the user that has updated the Ruleset last. Read-only. | | `rulesets[].updater.id` | string | | Read-only. | | `rulesets[].updater.type` | string | | A string that determines the schema of the object. Read-only. | | `rulesets[].updater.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `rulesets[].team` | object | | Reference to the team that owns the Ruleset. If none is specified, only admins have access. | | `rulesets[].team.id` | string | yes | | | `rulesets[].team.type` | string | yes | A string that determines the schema of the object. Read-only. | | `rulesets[].team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "rulesets": [ { "id": "0e84de00-9511-4380-9f4f-a7b568bb49a0", "name": "MySQL Clusters", "type": "global", "routing_keys": [ "R0212P1QXGEIQE2NMTQ7L7WXD00DWHIN" ], "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0", "created_at": "2019-12-24T21:18:52Z", "creator": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "updated_at": "2019-12-25T14:54:23Z", "updater": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "team": { "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF", "id": "P3ZQXDF" } } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/update-ruleset # Update a Ruleset `PUT https://api.pagerduty.com/rulesets/{id}` Update a Ruleset. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `ruleset` | object | yes | | | `ruleset.id` | string | | ID of the Ruleset. Read-only. | | `ruleset.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `ruleset.type` | string | | Read-only. One of: `global`, `default_global`. | | `ruleset.name` | string | | Name of the Ruleset. | | `ruleset.routing_keys` | array of string | | Routing keys routed to this Ruleset. Read-only. | | `ruleset.created_at` | string (date-time) | | The date the Ruleset was created at. Read-only. | | `ruleset.creator` | object | | Reference to the user that has created the Ruleset. Read-only. | | `ruleset.creator.id` | string | | Read-only. | | `ruleset.creator.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.creator.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.updated_at` | string (date-time) | | The date the Ruleset was last updated. Read-only. | | `ruleset.updater` | object | | Reference to the user that has updated the Ruleset last. Read-only. | | `ruleset.updater.id` | string | | Read-only. | | `ruleset.updater.type` | string | | A string that determines the schema of the object. Read-only. | | `ruleset.updater.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `ruleset.team` | object | | Reference to the team that owns the Ruleset. If none is specified, only admins have access. | | `ruleset.team.id` | string | yes | | | `ruleset.team.type` | string | yes | A string that determines the schema of the object. Read-only. | | `ruleset.team.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | Example: Example: Change name ```json { "ruleset": { "name": "MySQL Clusters" } } ``` Example: Example: Change team ```json { "ruleset": { "team": { "id": "PWL7QXS", "type": "team_reference" } } } ``` ## Response 200 The Ruleset that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `ruleset` | object | | Same fields as `ruleset` above. | Example: Response Example ```json { "rulesets": { "id": "0e84de00-9511-4380-9f4f-a7b568bb49a0", "name": "MySQL Clusters", "type": "global", "routing_keys": [ "R0212P1QXGEIQE2NMTQ7L7WXD00DWHIN" ], "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0", "created_at": "2019-12-24T21:18:52Z", "creator": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "updated_at": "2019-12-25T14:54:23Z", "updater": { "type": "user_reference", "self": "https://api.pagerduty.com/users/PABO808", "id": "PABO808" }, "team": { "type": "team_reference", "self": "https://api.pagerduty.com/teams/P3ZQXDF", "id": "P3ZQXDF" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/rulesets/update-ruleset-event-rule # Update an Event Rule `PUT https://api.pagerduty.com/rulesets/{id}/rules/{rule_id}` Update an Event Rule. Note that the endpoint supports partial updates, so any number of the writable fields can be provided. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Rulesets allow you to route events to an endpoint and create collections of Event Rules, which define sets of actions to take based on event content. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#rulesets) Note: Create and Update on rules will accept 'description' or 'summary' interchangeably as an extraction action target. Get and List on rules will always return 'summary' as the target. If you are expecting 'description' please change your automation code to expect 'summary' instead. Scoped OAuth requires: `event_rules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule in the Ruleset. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching rule is found. | | `rule.catch_all` | boolean | | Indicates whether the Event Rule is the last Event Rule of the Ruleset that serves as a catch-all. It has limited functionality compared to other rules and always matches. Read-only. | | `rule.actions` | object | | When an event matches this rule, the actions that will be taken to change the resulting alert and incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | | `rule.actions.route` | object \| null | | Set the service ID of the target service for the resulting alert. You can find the service you want to route to by calling the services endpoint. | | `rule.actions.route.value` | string | yes | The target service's ID. | | `rule_id` | string | yes | The id of the Event Rule to update. | Example: Example: Enable suppress action ```json { "rule_id": "7123bdd1-74e8-4aa7-aa38-4a9ebe123456", "rule": { "actions": { "suppress": { "value": true } } } } ``` Example: Example: Disable rule ```json { "rule_id": "7123bdd1-74e8-4aa7-aa38-4a9ebe123456", "rule": { "disabled": true, "actions": { "suppress": { "value": true } } } } ``` ## Response 200 The Event Rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | Same fields as `rule` above. | Example: Response Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "catch_all": false, "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "details.host" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was created by a Global Event Rule" }, "route": { "value": "PI2KBWI" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/create-custom-shifts # Create custom shifts `POST https://api.pagerduty.com/v3/schedules/{id}/custom_shifts` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create one or more custom shifts for a schedule. Custom shifts are ad-hoc one-off coverage periods that exist outside of rotation events. Each custom shift requires exactly one assignment. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `custom_shifts` | array of object | yes | Min items: 1. | | `custom_shifts[].type` | string | yes | One of: `custom_shift`. | | `custom_shifts[].start_time` | string (date-time) | yes | | | `custom_shifts[].end_time` | string (date-time) | yes | | | `custom_shifts[].assignments` | array of object | yes | Min items: 1. Max items: 1. | | `custom_shifts[].assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shifts[].assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `custom_shifts[].assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `custom_shifts[].assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | Example: default ```json { "custom_shifts": [ { "type": "custom_shift", "start_time": "2025-03-15T09:00:00Z", "end_time": "2025-03-15T17:00:00Z", "assignments": [ { "type": "shift_assignment", "member": { "type": "user_member", "user_id": "PUSER123" } } ] } ] } ``` ## Response 201 Custom shifts created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_shifts` | array of object | yes | | | `custom_shifts[].id` | string | yes | | | `custom_shifts[].type` | string | yes | One of: `custom_shift`. | | `custom_shifts[].start_time` | string (date-time) | yes | | | `custom_shifts[].end_time` | string (date-time) | yes | | | `custom_shifts[].assignments` | array of object | yes | Exactly one assignment per custom shift. Min items: 1. Max items: 1. | | `custom_shifts[].assignments[].id` | string | yes | Assignment ID. | | `custom_shifts[].assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shifts[].assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `custom_shifts[].assignments[].member` above. | | `custom_shifts[].self` | string (uri) | | | | `custom_shifts[].html_url` | string (uri) | | | ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/create-event # Create an event `POST https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}/events` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create a new event that defines when and how users are on-call within a rotation. **Constraints:** - Maximum 5 events per rotation - Events within a rotation cannot overlap - `effective_since` must be in the future (past values are clamped to now) - All users referenced in `assignment_strategy.members` must exist and belong to the account ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `event` | object | yes | | | `event.name` | string | yes | Max length: 255. | | `event.start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `event.start_time.date_time` | string (date-time) | yes | The date and time. | | `event.start_time.time_zone` | string | yes | IANA timezone identifier. | | `event.end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.effective_since` | string (date-time) | yes | When this event starts producing shifts. Values in the past are clamped to the current time. Can be at most 12 months in the future. | | `event.effective_until` | string \| null (date-time) | | When this event stops producing shifts. Omit or null for indefinite. | | `event.recurrence` | array of string | yes | RFC 5545 recurrence rules. Must be an array containing exactly one RRULE, zero or more EXDATE, and zero or more RDATE. The RRULE can repeat at most once per hour. **UI editor constraints:** The shift-based schedule editor can only load an event when the RRULE satisfies all of the following: 1. A `FREQ` parameter is present. 2. `FREQ` is one of `WEEKLY`, `DAILY`, `MONTHLY`, or `HOURLY`. 3. All `BYDAY` values are standard two-letter day codes (`MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`). Events that violate any condition display a "can't be edited in the UI" modal and must be managed via the API. | | `event.assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `event.assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `event.assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `event.assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `event.assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `event.assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | Example: Rotating weekly event ```json { "event": { "name": "Weekly On-Call", "start_time": { "date_time": "2025-03-03T09:00:00Z", "time_zone": "America/New_York" }, "end_time": { "date_time": "2025-03-10T09:00:00Z", "time_zone": "America/New_York" }, "effective_since": "2025-03-03T00:00:00Z", "recurrence": [ "RRULE:FREQ=WEEKLY" ], "assignment_strategy": { "type": "rotating_member_assignment_strategy", "shifts_per_member": 1, "members": [ { "type": "user_member", "user_id": "PUSER123" }, { "type": "user_member", "user_id": "PUSER456" } ] } } } ``` Example: Every-member event (all members on-call simultaneously) ```json { "event": { "name": "All-Hands Coverage", "start_time": { "date_time": "2025-03-03T00:00:00Z", "time_zone": "UTC" }, "end_time": { "date_time": "2025-03-04T00:00:00Z", "time_zone": "UTC" }, "effective_since": "2025-03-03T00:00:00Z", "effective_until": "2025-06-01T00:00:00Z", "recurrence": [ "RRULE:FREQ=WEEKLY;BYDAY=MO" ], "assignment_strategy": { "type": "every_member_assignment_strategy", "members": [ { "type": "user_member", "user_id": "PUSER123" }, { "type": "user_member", "user_id": "PUSER456" } ] } } } ``` ## Response 201 Event created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event` | object | yes | An event defines when and how users are on-call within a rotation. It combines a recurring time window (`start_time`, `end_time`, `recurrence`) with an assignment strategy and an effective date range (`effective_since`, `effective_until`). | | `event.id` | string | yes | | | `event.type` | string | yes | One of: `schedule_event`. | | `event.name` | string | yes | Display name for this event. | | `event.start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `event.effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `event.recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `event.assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. Same fields as `event.assignment_strategy` above. | | `event.self` | string (uri) | | | | `event.html_url` | string (uri) | | | ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/create-overrides # Create overrides `POST https://api.pagerduty.com/v3/schedules/{id}/overrides` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create one or more overrides for a schedule. An override temporarily replaces a scheduled on-call member with a different member for a specific time period. Each override must reference either a `rotation_id` or a `custom_shift_id` (not both). The overriding member must belong to the account. **Note:** The create response wraps the result in an `overrides` array. Single-resource endpoints (get, update) wrap in `override` (singular). ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `overrides` | array of object | yes | Min items: 1. | | `overrides[].type` | string | | Optional. One of: `override_shift`. | | `overrides[].rotation_id` | string | | Mutually exclusive with custom_shift_id. | | `overrides[].custom_shift_id` | string | | Mutually exclusive with rotation_id. | | `overrides[].start_time` | string (date-time) | yes | Must be within one year from now. A value in the past is set to the current time. | | `overrides[].end_time` | string (date-time) | yes | | | `overrides[].overridden_member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `overrides[].overridden_member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `overrides[].overridden_member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `overrides[].overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `overrides[].overridden_member` above. | Example: default ```json { "overrides": [ { "type": "override_shift", "rotation_id": "ABCDEFGHIJKLMNOPQRSTUVWXY", "start_time": "2025-03-15T09:00:00Z", "end_time": "2025-03-15T17:00:00Z", "overridden_member": { "type": "user_member", "user_id": "PUSER123" }, "overriding_member": { "type": "user_member", "user_id": "PUSER456" } } ] } ``` ## Response 201 Overrides created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `overrides` | array of object | yes | | | `overrides[].id` | string | yes | | | `overrides[].type` | string | yes | One of: `override_shift`. | | `overrides[].rotation_id` | string | | ID of the rotation whose shift is being overridden (mutually exclusive with custom_shift_id) | | `overrides[].custom_shift_id` | string | | ID of the custom shift being overridden (mutually exclusive with rotation_id) | | `overrides[].start_time` | string (date-time) | yes | | | `overrides[].end_time` | string (date-time) | yes | | | `overrides[].overridden_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `overrides[].overridden_member` above. | | `overrides[].overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `overrides[].overridden_member` above. | | `overrides[].self` | string (uri) | | | | `overrides[].html_url` | string (uri) | | | ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/create-rotation # Create a rotation `POST https://api.pagerduty.com/v3/schedules/{id}/rotations` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create a new empty rotation for a schedule. After creating a rotation, add events to define the on-call pattern. **Note:** Rotations have no configuration of their own — all scheduling logic (recurrence, assignment strategy, members) is specified on events. The request body must be empty or `{}`. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Request body (`application/json`) Type: object ## Response 201 Rotation created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rotation` | object | yes | A rotation within a schedule. All scheduling logic (recurrence, assignment strategy, members) is defined on the rotation's events. | | `rotation.id` | string | yes | | | `rotation.type` | string | yes | One of: `schedule_rotation`. | | `rotation.events` | array of object | | Events in this rotation. | | `rotation.events[].id` | string | yes | | | `rotation.events[].type` | string | yes | One of: `schedule_event`. | | `rotation.events[].name` | string | yes | Display name for this event. | | `rotation.events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `rotation.events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `rotation.events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `rotation.events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `rotation.events[].start_time` above. | | `rotation.events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `rotation.events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `rotation.events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `rotation.events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `rotation.events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `rotation.events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `rotation.events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `rotation.events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `rotation.events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `rotation.events[].self` | string (uri) | | | | `rotation.events[].html_url` | string (uri) | | | | `rotation.self` | string (uri) | | | | `rotation.html_url` | string (uri) | | | ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/create-schedule-v3 # Create a schedule `POST https://api.pagerduty.com/v3/schedules` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Create a new on-call schedule with basic metadata. Rotations and events must be added via separate API calls after creation. **Rejected fields:** `rotations` and `escalation_policies` are not accepted in the request body and will result in a 400 error. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.name` | string | yes | Min length: 1. Max length: 255. | | `schedule.time_zone` | string | yes | IANA timezone identifier. | | `schedule.description` | string | | Max length: 1024. | | `schedule.teams` | array of object | | Teams to associate with this schedule. | | `schedule.teams[].id` | string | yes | | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | Example: Minimal schedule ```json { "schedule": { "name": "Engineering On-Call", "time_zone": "America/New_York" } } ``` Example: Schedule with teams ```json { "schedule": { "name": "Engineering On-Call", "time_zone": "UTC", "description": "Engineering team on-call schedule", "teams": [ { "id": "PTEAM123", "type": "team_reference" } ] } } ``` ## Response 201 Schedule created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | yes | | | `schedule.type` | string | yes | Always `"schedule_v3"` for schedules created with this API. Schedules created with the legacy `/schedules` API use `"schedule"`. One of: `schedule_v3`. | | `schedule.name` | string | yes | | | `schedule.time_zone` | string | yes | | | `schedule.description` | string | | | | `schedule.teams` | array of object | | | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.escalation_policies` | array of object | | Escalation policies that reference this schedule. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | All users referenced in this schedule (only present when include[]=users) | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.rotations` | array of object | | Rotations in this schedule. | | `schedule.rotations[].id` | string | yes | | | `schedule.rotations[].type` | string | yes | One of: `schedule_rotation`. | | `schedule.rotations[].events` | array of object | | Events in this rotation. | | `schedule.rotations[].events[].id` | string | yes | | | `schedule.rotations[].events[].type` | string | yes | One of: `schedule_event`. | | `schedule.rotations[].events[].name` | string | yes | Display name for this event. | | `schedule.rotations[].events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `schedule.rotations[].events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `schedule.rotations[].events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `schedule.rotations[].events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `schedule.rotations[].events[].start_time` above. | | `schedule.rotations[].events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `schedule.rotations[].events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `schedule.rotations[].events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `schedule.rotations[].events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `schedule.rotations[].events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `schedule.rotations[].events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `schedule.rotations[].events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `schedule.rotations[].events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.rotations[].events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.rotations[].events[].self` | string (uri) | | | | `schedule.rotations[].events[].html_url` | string (uri) | | | | `schedule.rotations[].self` | string (uri) | | | | `schedule.rotations[].html_url` | string (uri) | | | | `schedule.final_schedule` | object | | Computed on-call assignments for the requested time range. Only present when `include[]=final_schedule` is specified and `since`/`until` are provided. | | `schedule.final_schedule.type` | string | yes | One of: `final_schedule`. | | `schedule.final_schedule.rendered_coverage_percentage` | number (double) | yes | Percentage of the requested time range that has on-call coverage (0–100) | | `schedule.final_schedule.computed_shift_assignments` | array of object | yes | | | `schedule.final_schedule.computed_shift_assignments[].type` | string | yes | One of: `computed_shift_assignment`. | | `schedule.final_schedule.computed_shift_assignments[].start_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].end_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `schedule.final_schedule.computed_shift_assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.final_schedule.computed_shift_assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.final_schedule.computed_shift_assignments[].source` | object | yes | Where a computed shift assignment originated. | | `schedule.final_schedule.computed_shift_assignments[].source.type` | string | yes | One of: `schedule_rotation`, `custom_shift`, `schedule_rotation_override`, `custom_shift_override`. | | `schedule.final_schedule.computed_shift_assignments[].source.rotation_id` | string | | Present for schedule_rotation and schedule_rotation_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.shift_id` | string | | Present for custom_shift and custom_shift_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.override_id` | string | | Present for schedule_rotation_override and custom_shift_override sources. | | `schedule.http_cal_url` | string (uri) | | iCal HTTP feed URL for this schedule. | | `schedule.web_cal_url` | string (uri) | | iCal webcal URL for this schedule. | | `schedule.self` | string (uri) | | | | `schedule.html_url` | string (uri) | | | ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/delete-custom-shift # Delete a custom shift `DELETE https://api.pagerduty.com/v3/schedules/{id}/custom_shifts/{custom_shift_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete a custom shift by ID. When the shift is not started, it deletes the shift entirely. If the shift is already started, it sets the end_time to now. It returns Bad Request when shift is already ended. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `custom_shift_id` | string | yes | The ID of the custom shift. | ## Response 204 Custom shift deleted successfully ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/delete-event # Delete an event `DELETE https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}/events/{event_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete an event from a rotation. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | | `event_id` | string | yes | The ID of the event. | ## Response 204 Event deleted successfully ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/delete-override # Delete an override `DELETE https://api.pagerduty.com/v3/schedules/{id}/overrides/{override_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete an override by ID. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `override_id` | string | yes | The ID of the override. | ## Response 204 Override deleted successfully ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/delete-rotation # Delete a rotation `DELETE https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete a rotation and all its events. On deletion, past events are preserved in the audit history, the current active event is truncated to the deletion time, and future events are removed. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | ## Response 204 Rotation deleted successfully ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/delete-schedule-v3 # Delete a schedule `DELETE https://api.pagerduty.com/v3/schedules/{id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Delete a schedule and all associated rotations and events. If the schedule is referenced by an active escalation policy, the deletion will be rejected. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Response 204 Schedule deleted successfully ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/get-custom-shift # Get a custom shift `GET https://api.pagerduty.com/v3/schedules/{id}/custom_shifts/{custom_shift_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a single custom shift by ID. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `custom_shift_id` | string | yes | The ID of the custom shift. | ## Response 200 Custom shift retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_shift` | object | yes | An ad-hoc one-off shift outside of rotation events. | | `custom_shift.id` | string | yes | | | `custom_shift.type` | string | yes | One of: `custom_shift`. | | `custom_shift.start_time` | string (date-time) | yes | | | `custom_shift.end_time` | string (date-time) | yes | | | `custom_shift.assignments` | array of object | yes | Exactly one assignment per custom shift. Min items: 1. Max items: 1. | | `custom_shift.assignments[].id` | string | yes | Assignment ID. | | `custom_shift.assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shift.assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `custom_shift.assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `custom_shift.assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `custom_shift.self` | string (uri) | | | | `custom_shift.html_url` | string (uri) | | | Example: Example response ```json { "custom_shift": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "custom_shift", "start_time": "2025-03-15T09:00:00Z", "end_time": "2025-03-15T17:00:00Z", "assignments": [ { "id": "AGOQEAQOOJ3UDGC22OGLXLIRY4", "member": { "type": "user_member", "user_id": "PNFNM8M" }, "type": "shift_assignment" } ], "self": "https://api.pagerduty.com/v3/schedules/PI7DH85/custom_shifts/ABCDE12345FGHIJ67890KLMNO", "html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/get-event # Get an event `GET https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}/events/{event_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a specific event by ID. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | | `event_id` | string | yes | The ID of the event. | ## Response 200 Event retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event` | object | yes | An event defines when and how users are on-call within a rotation. It combines a recurring time window (`start_time`, `end_time`, `recurrence`) with an assignment strategy and an effective date range (`effective_since`, `effective_until`). | | `event.id` | string | yes | | | `event.type` | string | yes | One of: `schedule_event`. | | `event.name` | string | yes | Display name for this event. | | `event.start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `event.start_time.date_time` | string (date-time) | yes | The date and time. | | `event.start_time.time_zone` | string | yes | IANA timezone identifier. | | `event.end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `event.effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `event.recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `event.assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `event.assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `event.assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `event.assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `event.assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `event.assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `event.self` | string (uri) | | | | `event.html_url` | string (uri) | | | Example: Example response ```json { "event": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "event", "name": "Weekly On-Call" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/get-override # Get an override `GET https://api.pagerduty.com/v3/schedules/{id}/overrides/{override_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a single override by ID. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `override_id` | string | yes | The ID of the override. | ## Response 200 Override retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `override` | object | yes | Temporarily replaces a scheduled on-call member for a specific time period. References either a `rotation_id` or a `custom_shift_id` to identify the source shift being overridden (not both). | | `override.id` | string | yes | | | `override.type` | string | yes | One of: `override_shift`. | | `override.rotation_id` | string | | ID of the rotation whose shift is being overridden (mutually exclusive with custom_shift_id) | | `override.custom_shift_id` | string | | ID of the custom shift being overridden (mutually exclusive with rotation_id) | | `override.start_time` | string (date-time) | yes | | | `override.end_time` | string (date-time) | yes | | | `override.overridden_member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `override.overridden_member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `override.overridden_member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `override.overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `override.overridden_member` above. | | `override.self` | string (uri) | | | | `override.html_url` | string (uri) | | | Example: Example response ```json { "override": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "override_shift", "start_time": "2025-03-15T09:00:00Z", "end_time": "2025-03-15T17:00:00Z" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/get-rotation # Get a rotation `GET https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a rotation by ID including all its events. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | ## Response 200 Rotation retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rotation` | object | yes | A rotation within a schedule. All scheduling logic (recurrence, assignment strategy, members) is defined on the rotation's events. | | `rotation.id` | string | yes | | | `rotation.type` | string | yes | One of: `schedule_rotation`. | | `rotation.events` | array of object | | Events in this rotation. | | `rotation.events[].id` | string | yes | | | `rotation.events[].type` | string | yes | One of: `schedule_event`. | | `rotation.events[].name` | string | yes | Display name for this event. | | `rotation.events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `rotation.events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `rotation.events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `rotation.events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `rotation.events[].start_time` above. | | `rotation.events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `rotation.events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `rotation.events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `rotation.events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `rotation.events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `rotation.events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `rotation.events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `rotation.events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `rotation.events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `rotation.events[].self` | string (uri) | | | | `rotation.events[].html_url` | string (uri) | | | | `rotation.self` | string (uri) | | | | `rotation.html_url` | string (uri) | | | Example: Example response ```json { "rotation": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "rotation", "schedule": { "id": "PS1A2B3C", "type": "schedule_v3_reference" }, "events": [] } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/get-schedule-v3 # Get a schedule `GET https://api.pagerduty.com/v3/schedules/{id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a schedule by ID including rotations and events. Optionally include the computed final schedule for a time range. Use `include[]=final_schedule` to get computed on-call assignments. Use `since` and `until` to specify the time range. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | Start of time range (ISO 8601). Send `since` and `until` together. `since` can be at most 3 years in the future. | | `until` | string (date-time) | | End of time range (ISO 8601). Send `since` and `until` together. `until` must be after `since`, and can be at most 3 years and 2 weeks in the future. | | `time_zone` | string | | IANA timezone identifier for rendering shift times. Defaults to the schedule's configured time zone. | | `overflow` | boolean | | Include shifts that extend beyond the requested time range boundaries. Default: `false`. | | `include[]` | array of string | | Additional data to include in the schedule response: - `final_schedule`: computed on-call assignments for the time range - `users`: all users referenced in the schedule. | ## Response 200 Schedule retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | yes | | | `schedule.type` | string | yes | Always `"schedule_v3"` for schedules created with this API. Schedules created with the legacy `/schedules` API use `"schedule"`. One of: `schedule_v3`. | | `schedule.name` | string | yes | | | `schedule.time_zone` | string | yes | | | `schedule.description` | string | | | | `schedule.teams` | array of object | | | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.escalation_policies` | array of object | | Escalation policies that reference this schedule. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | All users referenced in this schedule (only present when include[]=users) | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.rotations` | array of object | | Rotations in this schedule. | | `schedule.rotations[].id` | string | yes | | | `schedule.rotations[].type` | string | yes | One of: `schedule_rotation`. | | `schedule.rotations[].events` | array of object | | Events in this rotation. | | `schedule.rotations[].events[].id` | string | yes | | | `schedule.rotations[].events[].type` | string | yes | One of: `schedule_event`. | | `schedule.rotations[].events[].name` | string | yes | Display name for this event. | | `schedule.rotations[].events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `schedule.rotations[].events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `schedule.rotations[].events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `schedule.rotations[].events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `schedule.rotations[].events[].start_time` above. | | `schedule.rotations[].events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `schedule.rotations[].events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `schedule.rotations[].events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `schedule.rotations[].events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `schedule.rotations[].events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `schedule.rotations[].events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `schedule.rotations[].events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `schedule.rotations[].events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.rotations[].events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.rotations[].events[].self` | string (uri) | | | | `schedule.rotations[].events[].html_url` | string (uri) | | | | `schedule.rotations[].self` | string (uri) | | | | `schedule.rotations[].html_url` | string (uri) | | | | `schedule.final_schedule` | object | | Computed on-call assignments for the requested time range. Only present when `include[]=final_schedule` is specified and `since`/`until` are provided. | | `schedule.final_schedule.type` | string | yes | One of: `final_schedule`. | | `schedule.final_schedule.rendered_coverage_percentage` | number (double) | yes | Percentage of the requested time range that has on-call coverage (0–100) | | `schedule.final_schedule.computed_shift_assignments` | array of object | yes | | | `schedule.final_schedule.computed_shift_assignments[].type` | string | yes | One of: `computed_shift_assignment`. | | `schedule.final_schedule.computed_shift_assignments[].start_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].end_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `schedule.final_schedule.computed_shift_assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.final_schedule.computed_shift_assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.final_schedule.computed_shift_assignments[].source` | object | yes | Where a computed shift assignment originated. | | `schedule.final_schedule.computed_shift_assignments[].source.type` | string | yes | One of: `schedule_rotation`, `custom_shift`, `schedule_rotation_override`, `custom_shift_override`. | | `schedule.final_schedule.computed_shift_assignments[].source.rotation_id` | string | | Present for schedule_rotation and schedule_rotation_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.shift_id` | string | | Present for custom_shift and custom_shift_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.override_id` | string | | Present for schedule_rotation_override and custom_shift_override sources. | | `schedule.http_cal_url` | string (uri) | | iCal HTTP feed URL for this schedule. | | `schedule.web_cal_url` | string (uri) | | iCal webcal URL for this schedule. | | `schedule.self` | string (uri) | | | | `schedule.html_url` | string (uri) | | | Example: Example response ```json { "schedule": { "id": "PS1A2B3C", "type": "schedule_v3", "name": "Engineering On-Call", "time_zone": "America/New_York", "self": "https://api.pagerduty.com/v3/schedules/PS1A2B3C" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-custom-shifts # List custom shifts `GET https://api.pagerduty.com/v3/schedules/{id}/custom_shifts` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve custom shifts for a schedule within a time range. **`since` and `until` are required.** Returns every custom shift that overlaps the window. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | yes | Start of time range (ISO 8601). Can be at most 2 years in the future. | | `until` | string (date-time) | yes | End of time range (ISO 8601). Can be at most 2 years and 2 weeks in the future. | | `time_zone` | string | | IANA timezone identifier for rendering shift times. Defaults to the schedule's configured time zone. | | `overflow` | boolean | | Include shifts that extend beyond the requested time range boundaries. Default: `false`. | ## Response 200 Custom shifts retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_shifts` | array of object | yes | | | `custom_shifts[].id` | string | yes | | | `custom_shifts[].type` | string | yes | One of: `custom_shift`. | | `custom_shifts[].start_time` | string (date-time) | yes | | | `custom_shifts[].end_time` | string (date-time) | yes | | | `custom_shifts[].assignments` | array of object | yes | Exactly one assignment per custom shift. Min items: 1. Max items: 1. | | `custom_shifts[].assignments[].id` | string | yes | Assignment ID. | | `custom_shifts[].assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shifts[].assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `custom_shifts[].assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `custom_shifts[].assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `custom_shifts[].self` | string (uri) | | | | `custom_shifts[].html_url` | string (uri) | | | Example: Example response ```json { "custom_shifts": [] } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-events # List events `GET https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}/events` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve all events for a rotation, ordered by start time. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Maximum number of items to return. Default: `100`. Minimum: 1. Maximum: 1000. | | `offset` | integer | | Default: `0`. Minimum: 0. | ## Response 200 Events retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `events` | array of object | yes | | | `events[].id` | string | yes | | | `events[].type` | string | yes | One of: `schedule_event`. | | `events[].name` | string | yes | Display name for this event. | | `events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `events[].start_time` above. | | `events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `events[].self` | string (uri) | | | | `events[].html_url` | string (uri) | | | | `limit` | integer | | | | `offset` | integer | | | | `more` | boolean | | | Example: Example response ```json { "events": [], "limit": 25, "offset": 0, "more": false } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-overrides # List overrides `GET https://api.pagerduty.com/v3/schedules/{id}/overrides` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve overrides for a schedule within a time range. **`since` and `until` are required.** Returns every override that overlaps the window. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | yes | Start of time range (ISO 8601). Can be at most 2 years in the future. | | `until` | string (date-time) | yes | End of time range (ISO 8601). Can be at most 2 years and 2 weeks in the future. | | `time_zone` | string | | IANA timezone identifier for rendering shift times. Defaults to the schedule's configured time zone. | | `overflow` | boolean | | Include shifts that extend beyond the requested time range boundaries. Default: `false`. | ## Response 200 Overrides retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `overrides` | array of object | yes | | | `overrides[].id` | string | yes | | | `overrides[].type` | string | yes | One of: `override_shift`. | | `overrides[].rotation_id` | string | | ID of the rotation whose shift is being overridden (mutually exclusive with custom_shift_id) | | `overrides[].custom_shift_id` | string | | ID of the custom shift being overridden (mutually exclusive with rotation_id) | | `overrides[].start_time` | string (date-time) | yes | | | `overrides[].end_time` | string (date-time) | yes | | | `overrides[].overridden_member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `overrides[].overridden_member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `overrides[].overridden_member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `overrides[].overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `overrides[].overridden_member` above. | | `overrides[].self` | string (uri) | | | | `overrides[].html_url` | string (uri) | | | Example: Example response ```json { "overrides": [] } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-rotations # List rotations `GET https://api.pagerduty.com/v3/schedules/{id}/rotations` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve all rotations for a schedule. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Maximum number of items to return. Default: `100`. Minimum: 1. Maximum: 1000. | | `offset` | integer | | Default: `0`. Minimum: 0. | ## Response 200 Rotations retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rotations` | array of object | yes | | | `rotations[].id` | string | yes | | | `rotations[].type` | string | yes | One of: `schedule_rotation`. | | `rotations[].events` | array of object | | Events in this rotation. | | `rotations[].events[].id` | string | yes | | | `rotations[].events[].type` | string | yes | One of: `schedule_event`. | | `rotations[].events[].name` | string | yes | Display name for this event. | | `rotations[].events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `rotations[].events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `rotations[].events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `rotations[].events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `rotations[].events[].start_time` above. | | `rotations[].events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `rotations[].events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `rotations[].events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `rotations[].events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `rotations[].events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `rotations[].events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `rotations[].events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `rotations[].events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `rotations[].events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `rotations[].events[].self` | string (uri) | | | | `rotations[].events[].html_url` | string (uri) | | | | `rotations[].self` | string (uri) | | | | `rotations[].html_url` | string (uri) | | | | `limit` | integer | | | | `offset` | integer | | | | `more` | boolean | | | Example: Example response ```json { "rotations": [ { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "rotation" } ], "limit": 25, "offset": 0, "more": false } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-schedules-audit-records-v3 # List audit records for a schedule `GET https://api.pagerduty.com/v3/schedules/{id}/audit/records` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PD_ASSIGN_TEAM_TO_SCHEDULE", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_TEAM123", "summary": "Devops", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" } ], "name": "teams" } ], "resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, "execution_context": { "request_id": "13a1c0c3-545c-4ebb-4115-662fff9d8ad" }, "execution_time": "2021-01-05T16:25:41.324Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, { "id": "PD_CREATE_SCHEDULE", "action": "create", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "name", "value": "DevOps Schedule" }, { "name": "description", "value": "Our DevOps Team Schedule" }, { "name": "time_zone", "value": "America/New_York" } ], "resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, "execution_context": { "request_id": "13a1c0c3-545c-4ebb-4115-662fff9d8ad" }, "execution_time": "2021-01-05T16:25:41.315Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/list-schedules-v3 # List schedules `GET https://api.pagerduty.com/v3/schedules` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Retrieve a paginated list of schedule references. Returns lightweight objects without embedded rotations or events. Each result is filtered by the caller's read permission; schedules the caller cannot read are silently excluded. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Maximum number of schedules to return. Default: `25`. Minimum: 1. Maximum: 100. | | `offset` | integer | | Default: `0`. Minimum: 0. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `user_id` | string | | Return only schedules that include this user. | ## Response 200 Schedules retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedules` | array of object | yes | | | `schedules[].id` | string | yes | | | `schedules[].type` | string | yes | One of: `schedule_v3_reference`. | | `schedules[].summary` | string | yes | Schedule name. | | `schedules[].self` | string (uri) | | | | `schedules[].html_url` | string (uri) | | | | `limit` | integer | | | | `offset` | integer | | | | `more` | boolean | | Whether additional results exist beyond this page. | Example: Example response ```json { "schedules": [ { "id": "PS1A2B3C", "type": "schedule_v3_reference", "summary": "Engineering On-Call", "self": "https://api.pagerduty.com/v3/schedules/PS1A2B3C", "html_url": "https://subdomain.pagerduty.com/schedules/PS1A2B3C" } ], "limit": 100, "offset": 0, "more": false } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/update-custom-shift # Update a custom shift `PUT https://api.pagerduty.com/v3/schedules/{id}/custom_shifts/{custom_shift_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Update an existing custom shift. If the shift has already started, only `end_time` can be modified. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `custom_shift_id` | string | yes | The ID of the custom shift. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `custom_shift` | object | yes | The request replaces the full custom shift. Send every required field, even the fields that do not change. If the shift has already started, only `end_time` can be modified. | | `custom_shift.type` | string | yes | One of: `custom_shift`. | | `custom_shift.start_time` | string (date-time) | yes | | | `custom_shift.end_time` | string (date-time) | yes | | | `custom_shift.assignments` | array of object | yes | Min items: 1. Max items: 1. | | `custom_shift.assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shift.assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `custom_shift.assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `custom_shift.assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | Example: default ```json { "custom_shift": { "type": "custom_shift", "start_time": "2025-03-15T10:00:00Z", "end_time": "2025-03-15T18:00:00Z", "assignments": [ { "type": "shift_assignment", "member": { "type": "user_member", "user_id": "PUSER456" } } ] } } ``` ## Response 200 Custom shift updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_shift` | object | yes | An ad-hoc one-off shift outside of rotation events. | | `custom_shift.id` | string | yes | | | `custom_shift.type` | string | yes | One of: `custom_shift`. | | `custom_shift.start_time` | string (date-time) | yes | | | `custom_shift.end_time` | string (date-time) | yes | | | `custom_shift.assignments` | array of object | yes | Exactly one assignment per custom shift. Min items: 1. Max items: 1. | | `custom_shift.assignments[].id` | string | yes | Assignment ID. | | `custom_shift.assignments[].type` | string | yes | One of: `shift_assignment`. | | `custom_shift.assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `custom_shift.assignments[].member` above. | | `custom_shift.self` | string (uri) | | | | `custom_shift.html_url` | string (uri) | | | Example: Example response ```json { "custom_shift": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "custom_shift", "start_time": "2025-03-15T10:00:00Z", "end_time": "2025-03-15T18:00:00Z", "assignments": [ { "id": "AGOQEAQOOJ3UDGC22OGLXLIRY4", "member": { "type": "user_member", "user_id": "PNFNM8M" }, "type": "shift_assignment" } ], "self": "https://api.pagerduty.com/v3/schedules/PI7DH85/custom_shifts/ABCDE12345FGHIJ67890KLMNO", "html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85" } } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/update-event # Update an event `PUT https://api.pagerduty.com/v3/schedules/{id}/rotations/{rotation_id}/events/{event_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Update an existing event. **Restrictions based on event timing:** - **Past events** (effective_until in the past): Cannot be modified - **Active events** (currently producing shifts): Can only update `effective_until` - **Future events** (effective_since in the future): All fields can be updated ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `rotation_id` | string | yes | The ID of the rotation. | | `event_id` | string | yes | The ID of the event. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `event` | object | yes | | | `event.name` | string | yes | Max length: 255. | | `event.start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `event.start_time.date_time` | string (date-time) | yes | The date and time. | | `event.start_time.time_zone` | string | yes | IANA timezone identifier. | | `event.end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.effective_since` | string (date-time) | yes | Can be at most 12 months in the future. | | `event.effective_until` | string \| null (date-time) | | | | `event.recurrence` | array of string | yes | RFC 5545 recurrence rules. Must be an array containing exactly one RRULE, zero or more EXDATE, and zero or more RDATE. The RRULE can repeat at most once per hour. **UI editor constraints:** The shift-based schedule editor can only load an event when the RRULE satisfies all of the following: 1. A `FREQ` parameter is present. 2. `FREQ` is one of `WEEKLY`, `DAILY`, `MONTHLY`, or `HOURLY`. 3. All `BYDAY` values are standard two-letter day codes (`MO`, `TU`, `WE`, `TH`, `FR`, `SA`, `SU`). Events that violate any condition display a "can't be edited in the UI" modal and must be managed via the API. | | `event.assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `event.assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `event.assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `event.assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `event.assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `event.assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | Example: Extend an active event's end date ```json { "event": { "name": "Weekly On-Call", "start_time": { "date_time": "2025-03-03T09:00:00Z", "time_zone": "America/New_York" }, "end_time": { "date_time": "2025-03-10T09:00:00Z", "time_zone": "America/New_York" }, "effective_since": "2025-03-03T00:00:00Z", "effective_until": "2025-09-01T00:00:00Z", "recurrence": [ "RRULE:FREQ=WEEKLY" ], "assignment_strategy": { "type": "rotating_member_assignment_strategy", "shifts_per_member": 1, "members": [ { "type": "user_member", "user_id": "PUSER123" }, { "type": "user_member", "user_id": "PUSER456" } ] } } } ``` Example: Update a future event ```json { "event": { "name": "Updated Weekly On-Call", "start_time": { "date_time": "2025-10-06T09:00:00Z", "time_zone": "America/New_York" }, "end_time": { "date_time": "2025-10-13T09:00:00Z", "time_zone": "America/New_York" }, "effective_since": "2025-10-06T00:00:00Z", "recurrence": [ "RRULE:FREQ=WEEKLY" ], "assignment_strategy": { "type": "rotating_member_assignment_strategy", "shifts_per_member": 1, "members": [ { "type": "user_member", "user_id": "PUSER789" } ] } } } ``` ## Response 200 Event updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `event` | object | yes | An event defines when and how users are on-call within a rotation. It combines a recurring time window (`start_time`, `end_time`, `recurrence`) with an assignment strategy and an effective date range (`effective_since`, `effective_until`). | | `event.id` | string | yes | | | `event.type` | string | yes | One of: `schedule_event`. | | `event.name` | string | yes | Display name for this event. | | `event.start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `event.start_time` above. | | `event.effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `event.effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `event.recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `event.assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. Same fields as `event.assignment_strategy` above. | | `event.self` | string (uri) | | | | `event.html_url` | string (uri) | | | Example: Example response ```json { "event": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "event", "name": "Updated Weekly On-Call" } } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/update-override # Update an override `PUT https://api.pagerduty.com/v3/schedules/{id}/overrides/{override_id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Update an existing override. Once the override has started, only `end_time` can be changed. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | | `override_id` | string | yes | The ID of the override. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `override` | object | yes | | | `override.type` | string | yes | One of: `override_shift`. | | `override.start_time` | string (date-time) | yes | | | `override.end_time` | string (date-time) | yes | | | `override.overridden_member` | object | | A member (user) assigned to a shift or rotation slot. | | `override.overridden_member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `override.overridden_member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `override.overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `override.overridden_member` above. | Example: default ```json { "override": { "type": "override_shift", "start_time": "2025-03-15T10:00:00Z", "end_time": "2025-03-15T18:00:00Z", "overridden_member": { "type": "user_member", "user_id": "PUSER123" }, "overriding_member": { "type": "user_member", "user_id": "PUSER789" } } } ``` ## Response 200 Override updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `override` | object | yes | Temporarily replaces a scheduled on-call member for a specific time period. References either a `rotation_id` or a `custom_shift_id` to identify the source shift being overridden (not both). | | `override.id` | string | yes | | | `override.type` | string | yes | One of: `override_shift`. | | `override.rotation_id` | string | | ID of the rotation whose shift is being overridden (mutually exclusive with custom_shift_id) | | `override.custom_shift_id` | string | | ID of the custom shift being overridden (mutually exclusive with rotation_id) | | `override.start_time` | string (date-time) | yes | | | `override.end_time` | string (date-time) | yes | | | `override.overridden_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `override.overridden_member` above. | | `override.overriding_member` | object | yes | A member (user) assigned to a shift or rotation slot. Same fields as `override.overridden_member` above. | | `override.self` | string (uri) | | | | `override.html_url` | string (uri) | | | Example: Example response ```json { "override": { "id": "ABCDE12345FGHIJ67890KLMNO", "type": "override_shift", "start_time": "2025-03-15T10:00:00Z", "end_time": "2025-03-15T18:00:00Z" } } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules_v3/update-schedule-v3 # Update a schedule `PUT https://api.pagerduty.com/v3/schedules/{id}` > **Important note:** Shift-based schedules use the V3 API and are not compatible with V2 automations. **To create automations for Shift-Based Schedules, you need to:** > > 1. **Update your automations** to use the V3 API for all new shift-based schedules > 2. **Keep the V2 endpoint** for your existing schedules > > An upgrade tool for existing schedules is coming soon; your legacy schedules will keep working in the meantime. [Learn more](https://support.pagerduty.com/main/docs/shift-based-schedules-api-upgrade-examples). Update schedule metadata (name, description, time zone). `time_zone` is required; `name` and `description` are optional and keep their current values when omitted. To modify rotations or events, use their respective endpoints. **Rejected fields:** `rotations` and `escalation_policies` are not accepted and will result in a 400 error. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | `time_zone` is required. `name` and `description` are optional; an omitted field keeps its current value. | | `schedule.name` | string | | Min length: 1. Max length: 255. | | `schedule.time_zone` | string | yes | | | `schedule.description` | string | | Max length: 1024. | | `schedule.teams` | array of object | | Teams to associate with this schedule. | | `schedule.teams[].id` | string | yes | | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | Example: Update name only ```json { "schedule": { "name": "New Schedule Name" } } ``` Example: Update multiple fields ```json { "schedule": { "name": "Updated Schedule", "time_zone": "America/Los_Angeles", "description": "Updated description" } } ``` ## Response 200 Schedule updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | yes | | | `schedule.type` | string | yes | Always `"schedule_v3"` for schedules created with this API. Schedules created with the legacy `/schedules` API use `"schedule"`. One of: `schedule_v3`. | | `schedule.name` | string | yes | | | `schedule.time_zone` | string | yes | | | `schedule.description` | string | | | | `schedule.teams` | array of object | | | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.escalation_policies` | array of object | | Escalation policies that reference this schedule. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | All users referenced in this schedule (only present when include[]=users) | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.rotations` | array of object | | Rotations in this schedule. | | `schedule.rotations[].id` | string | yes | | | `schedule.rotations[].type` | string | yes | One of: `schedule_rotation`. | | `schedule.rotations[].events` | array of object | | Events in this rotation. | | `schedule.rotations[].events[].id` | string | yes | | | `schedule.rotations[].events[].type` | string | yes | One of: `schedule_event`. | | `schedule.rotations[].events[].name` | string | yes | Display name for this event. | | `schedule.rotations[].events[].start_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). | | `schedule.rotations[].events[].start_time.date_time` | string (date-time) | yes | The date and time. | | `schedule.rotations[].events[].start_time.time_zone` | string | yes | IANA timezone identifier. | | `schedule.rotations[].events[].end_time` | object | yes | A time-of-day value with an explicit time zone. Used for event `start_time` and `end_time` to define the recurring window of coverage (e.g., 9 AM–5 PM every Monday in New York). Same fields as `schedule.rotations[].events[].start_time` above. | | `schedule.rotations[].events[].effective_since` | string (date-time) | yes | When this event starts producing shifts (UTC) | | `schedule.rotations[].events[].effective_until` | string \| null (date-time) | | When this event stops producing shifts (UTC). Null means indefinite. | | `schedule.rotations[].events[].recurrence` | array of string | yes | RFC 5545 recurrence rules defining the repeating pattern. This must be an array containing:
- Exactly one RRULE
- Zero or more EXDATE
- Zero or more RDATE. | | `schedule.rotations[].events[].assignment_strategy` | object | yes | Defines how users are assigned on-call within an event's time window. - `rotating_member_assignment_strategy`: users rotate in sequence. `shifts_per_member` controls how many consecutive shift periods each member covers before rotating. - `every_member_assignment_strategy`: all listed members are on-call simultaneously for every occurrence. | | `schedule.rotations[].events[].assignment_strategy.type` | string | yes | One of: `rotating_member_assignment_strategy`, `every_member_assignment_strategy`. | | `schedule.rotations[].events[].assignment_strategy.shifts_per_member` | integer | | Required for `rotating_member_assignment_strategy`. Number of consecutive shift occurrences each member covers before the next member takes over. Must be omitted (or null) for `every_member_assignment_strategy`. **UI editor constraint:** When `recurrence` uses `FREQ=WEEKLY`, `shifts_per_member` must be evenly divisible by the number of days listed in the RRULE `BYDAY` parameter. Events that violate this are fully functional via the API but cannot be loaded in the web schedule editor. Minimum: 1. | | `schedule.rotations[].events[].assignment_strategy.members` | array of object | yes | Min items: 1. Max items: 60. | | `schedule.rotations[].events[].assignment_strategy.members[].type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.rotations[].events[].assignment_strategy.members[].user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.rotations[].events[].self` | string (uri) | | | | `schedule.rotations[].events[].html_url` | string (uri) | | | | `schedule.rotations[].self` | string (uri) | | | | `schedule.rotations[].html_url` | string (uri) | | | | `schedule.final_schedule` | object | | Computed on-call assignments for the requested time range. Only present when `include[]=final_schedule` is specified and `since`/`until` are provided. | | `schedule.final_schedule.type` | string | yes | One of: `final_schedule`. | | `schedule.final_schedule.rendered_coverage_percentage` | number (double) | yes | Percentage of the requested time range that has on-call coverage (0–100) | | `schedule.final_schedule.computed_shift_assignments` | array of object | yes | | | `schedule.final_schedule.computed_shift_assignments[].type` | string | yes | One of: `computed_shift_assignment`. | | `schedule.final_schedule.computed_shift_assignments[].start_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].end_time` | string (date-time) | yes | | | `schedule.final_schedule.computed_shift_assignments[].member` | object | yes | A member (user) assigned to a shift or rotation slot. | | `schedule.final_schedule.computed_shift_assignments[].member.type` | string | yes | `user_member` — a specific user is assigned. `empty_member` — the slot is intentionally unassigned. One of: `user_member`, `empty_member`. | | `schedule.final_schedule.computed_shift_assignments[].member.user_id` | string | | The ID of the user. Required when type is `user_member`. | | `schedule.final_schedule.computed_shift_assignments[].source` | object | yes | Where a computed shift assignment originated. | | `schedule.final_schedule.computed_shift_assignments[].source.type` | string | yes | One of: `schedule_rotation`, `custom_shift`, `schedule_rotation_override`, `custom_shift_override`. | | `schedule.final_schedule.computed_shift_assignments[].source.rotation_id` | string | | Present for schedule_rotation and schedule_rotation_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.shift_id` | string | | Present for custom_shift and custom_shift_override sources. | | `schedule.final_schedule.computed_shift_assignments[].source.override_id` | string | | Present for schedule_rotation_override and custom_shift_override sources. | | `schedule.http_cal_url` | string (uri) | | iCal HTTP feed URL for this schedule. | | `schedule.web_cal_url` | string (uri) | | iCal webcal URL for this schedule. | | `schedule.self` | string (uri) | | | | `schedule.html_url` | string (uri) | | | Example: Example response ```json { "schedule": { "id": "PS1A2B3C", "type": "schedule_v3", "name": "Updated Schedule", "time_zone": "America/Los_Angeles", "self": "https://api.pagerduty.com/v3/schedules/PS1A2B3C" } } ``` ## Response 400 Bad Request — The request contains invalid parameters or data ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | yes | | | `error.message` | string | yes | | | `error.code` | integer | yes | | | `error.errors` | object | | Map of field path to list of validation messages for that field. Field paths use dot notation prefixed by the resource type (e.g. `event.effective_since`, `rotation.events`). | Example: default ```json { "error": { "message": "Invalid Request", "code": 2001, "errors": { "event.effective_since": [ "Date cannot be more than 12 months in the future" ] } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/create-schedule # Create a schedule `POST https://api.pagerduty.com/schedules` Create a new on-call schedule. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `overflow` | boolean | | 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. For 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`: - 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`. - 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`. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The schedule to be created. | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | | Read-only. | | `schedule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.type` | string | yes | The type of object being created. One of: `schedule`. Default: `schedule`. | | `schedule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers` | array of object | | A list of schedule layers. | | `schedule.schedule_layers[].id` | string | | | | `schedule.schedule_layers[].start` | string (date-time) | yes | The start time of this layer. | | `schedule.schedule_layers[].end` | string (date-time) | | The end time of this layer. If `null`, the layer does not end. | | `schedule.schedule_layers[].users` | array of object | yes | The ordered list of users on this layer. The position of the user on the list determines their order in the layer. | | `schedule.schedule_layers[].users[].user` | object | yes | | | `schedule.schedule_layers[].users[].user.id` | string | yes | Read-only. | | `schedule.schedule_layers[].users[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.schedule_layers[].users[].user.type` | string | yes | One of: `user_reference`. | | `schedule.schedule_layers[].users[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.schedule_layers[].users[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers[].restrictions` | array of object | | An array of restrictions for the layer. A restriction is a limit on which period of the day or week the schedule layer can accept assignments. Restrictions respect the `time_zone` parameter of the request. | | `schedule.schedule_layers[].restrictions[].type` | string | yes | Specify the types of `restriction`. One of: `daily_restriction`, `weekly_restriction`. | | `schedule.schedule_layers[].restrictions[].duration_seconds` | integer | yes | The duration of the restriction in seconds. | | `schedule.schedule_layers[].restrictions[].start_time_of_day` | string (partial-time) | yes | The start time in HH:mm:ss format. | | `schedule.schedule_layers[].restrictions[].start_day_of_week` | integer | | Only required for use with a `weekly_restriction` restriction type. The first day of the weekly rotation schedule as [ISO 8601 day](https://en.wikipedia.org/wiki/ISO_week_date) (1 is Monday, etc.) Minimum: 1. Maximum: 7. | | `schedule.schedule_layers[].rotation_virtual_start` | string (date-time) | yes | The effective start time of the layer. This can be before the start time of the schedule. | | `schedule.schedule_layers[].rotation_turn_length_seconds` | integer | yes | The duration of each on-call shift in seconds. | | `schedule.schedule_layers[].name` | string | | The name of the schedule layer. | | `schedule.schedule_layers[].rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.schedule_layers[].rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.schedule_layers[].rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.time_zone` | string (activesupport-time-zone) | yes | The time zone of the schedule. | | `schedule.name` | string | | The name of the schedule. | | `schedule.description` | string | | The description of the schedule. | | `schedule.final_schedule` | object | | | | `schedule.final_schedule.name` | string | yes | The name of the subschedule. Read-only. One of: `Final Schedule`, `Overrides`. | | `schedule.final_schedule.rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.final_schedule.rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.final_schedule.rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.overrides_subschedule` | object | | Same fields as `schedule.final_schedule` above. | | `schedule.escalation_policies` | array of object | | An array of all of the escalation policies that uses this schedule. Read-only. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | An array of all of the users on the schedule. Read-only. | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.teams` | array of object | | An array of all of the teams on the schedule. Read-only. | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.next_oncall_for_user` | object | | | | `schedule.next_oncall_for_user.start` | string | | The start date for the User shift. Read-only. | | `schedule.next_oncall_for_user.end` | string | | The end date for the User shift. Read-only. | | `schedule.next_oncall_for_user.user` | object | | | | `schedule.next_oncall_for_user.user.id` | string | yes | Read-only. | | `schedule.next_oncall_for_user.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.next_oncall_for_user.user.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `schedule.next_oncall_for_user.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.next_oncall_for_user.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "schedule": { "name": "Daily Engineering Rotation", "type": "schedule", "time_zone": "America/New_York", "description": "Rotation schedule for engineering", "schedule_layers": [ { "name": "Night Shift", "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" } } ], "restrictions": [ { "type": "daily_restriction", "start_time_of_day": "08:00:00", "duration_seconds": 32400 } ] } ] } } ``` ## Response 201 The schedule object created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | Same fields as `schedule` above. | Example: Response Example ```json { "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": "PEYSGVF", "type": "user_reference", "summary": "PagerDuty Admin", "self": "https://api.pagerduty.com/users/PEYSGVF", "html_url": "https://subdomain.pagerduty.com/users/PEYSGVF" } ], "teams": [], "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": "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 } ] } ], "overrides_subschedule": { "name": "Overrides", "rendered_schedule_entries": [] }, "final_schedule": { "name": "Final Schedule", "rendered_schedule_entries": [] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/create-schedule-override # Create one or more overrides `POST https://api.pagerduty.com/schedules/{id}/overrides` Create one or more overrides, each for a specific user covering a specified time range. If you create an override on top of an existing override, the last created override will have priority. A Schedule determines the time periods that users are On-Call. Note: An older implementation of this endpoint only supported creating a single ocverride per request. That functionality is still supported, but deprecated and may be removed in the future. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required The overrides to be created | Field | Type | Required | Description | |---|---|---|---| | `overrides` | array of object | | | | `overrides[].id` | string | | Read-only. | | `overrides[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `overrides[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `overrides[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `overrides[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `overrides[].start` | string (date-time) | yes | The start date and time for the override. | | `overrides[].end` | string (date-time) | yes | The end date and time for the override. | | `overrides[].user` | object | yes | | | `overrides[].user.id` | string | yes | Read-only. | | `overrides[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `overrides[].user.type` | string | yes | One of: `user_reference`. | | `overrides[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `overrides[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "overrides": [ { "start": "2012-07-01T00:00:00-04:00", "end": "2012-07-02T00:00:00-04:00", "user": { "id": "PEYSGVA", "type": "user_reference" }, "time_zone": "UTC" }, { "start": "2012-07-03T00:00:00-04:00", "end": "2012-07-04T00:00:00-04:00", "user": { "id": "PEYSGVF", "type": "user_reference" }, "time_zone": "UTC" } ] } ``` ## Response 201 A list of overrides requested and a status code indicating whether they were created or rejected ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `[].status` | number | | HTTP Status Code reflecting the result of creating this specific override, e.g. 201 for success, 400 for invalid parameters. | | `[].errors` | array of string | | If present, an array of strings representing human-readable explanations for errors found. | | `[].override` | object | yes | | | `[].override.id` | string | | Read-only. | | `[].override.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `[].override.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `[].override.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `[].override.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `[].override.start` | string (date-time) | yes | The start date and time for the override. | | `[].override.end` | string (date-time) | yes | The end date and time for the override. | | `[].override.user` | object | yes | Same fields as `overrides[].user` above. | Example: Response Example ```json [ { "status": 201, "override": { "start": "2021-03-09T05:00:00Z", "end": "2021-03-09T17:00:00Z", "user": { "id": "P37CSDJ", "type": "user_reference", "summary": "Scott", "self": "https://api.pd-staging.com/users/P37CSDJ", "html_url": "https://pdt-braythwayt.pd-staging.com/users/P37CSDJ" }, "id": "Q3X6MJ1LUKD6QW" } }, { "status": 201, "override": { "start": "2021-03-10T05:00:00Z", "end": "2021-03-10T17:00:00Z", "user": { "id": "P37CSDJ", "type": "user_reference", "summary": "Scott", "self": "https://api.pd-staging.com/users/P37CSDJ", "html_url": "https://pdt-braythwayt.pd-staging.com/users/P37CSDJ" }, "id": "Q37A85CJZP1DTT" } }, { "status": 400, "errors": [ "Override must end after its start" ], "override": { "start": "2021-03-11T05:00:00Z", "end": "2021-03-11T05:00:00Z", "user": { "id": "P37CSDJ", "type": "user_reference", "summary": "Scott", "self": "https://api.pd-staging.com/users/P37CSDJ", "html_url": "https://pdt-braythwayt.pd-staging.com/users/P37CSDJ" } } } ] ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/create-schedule-preview # Preview a schedule `POST https://api.pagerduty.com/schedules/preview` Preview what an on-call schedule would look like without saving it. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | | `overflow` | boolean | | 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. For 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`: - 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`. - 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`. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The schedule to be previewed. | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | | Read-only. | | `schedule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.type` | string | yes | The type of object being created. One of: `schedule`. Default: `schedule`. | | `schedule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers` | array of object | | A list of schedule layers. | | `schedule.schedule_layers[].id` | string | | | | `schedule.schedule_layers[].start` | string (date-time) | yes | The start time of this layer. | | `schedule.schedule_layers[].end` | string (date-time) | | The end time of this layer. If `null`, the layer does not end. | | `schedule.schedule_layers[].users` | array of object | yes | The ordered list of users on this layer. The position of the user on the list determines their order in the layer. | | `schedule.schedule_layers[].users[].user` | object | yes | | | `schedule.schedule_layers[].users[].user.id` | string | yes | Read-only. | | `schedule.schedule_layers[].users[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.schedule_layers[].users[].user.type` | string | yes | One of: `user_reference`. | | `schedule.schedule_layers[].users[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.schedule_layers[].users[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers[].restrictions` | array of object | | An array of restrictions for the layer. A restriction is a limit on which period of the day or week the schedule layer can accept assignments. Restrictions respect the `time_zone` parameter of the request. | | `schedule.schedule_layers[].restrictions[].type` | string | yes | Specify the types of `restriction`. One of: `daily_restriction`, `weekly_restriction`. | | `schedule.schedule_layers[].restrictions[].duration_seconds` | integer | yes | The duration of the restriction in seconds. | | `schedule.schedule_layers[].restrictions[].start_time_of_day` | string (partial-time) | yes | The start time in HH:mm:ss format. | | `schedule.schedule_layers[].restrictions[].start_day_of_week` | integer | | Only required for use with a `weekly_restriction` restriction type. The first day of the weekly rotation schedule as [ISO 8601 day](https://en.wikipedia.org/wiki/ISO_week_date) (1 is Monday, etc.) Minimum: 1. Maximum: 7. | | `schedule.schedule_layers[].rotation_virtual_start` | string (date-time) | yes | The effective start time of the layer. This can be before the start time of the schedule. | | `schedule.schedule_layers[].rotation_turn_length_seconds` | integer | yes | The duration of each on-call shift in seconds. | | `schedule.schedule_layers[].name` | string | | The name of the schedule layer. | | `schedule.schedule_layers[].rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.schedule_layers[].rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.schedule_layers[].rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.time_zone` | string (activesupport-time-zone) | yes | The time zone of the schedule. | | `schedule.name` | string | | The name of the schedule. | | `schedule.description` | string | | The description of the schedule. | | `schedule.final_schedule` | object | | | | `schedule.final_schedule.name` | string | yes | The name of the subschedule. Read-only. One of: `Final Schedule`, `Overrides`. | | `schedule.final_schedule.rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.final_schedule.rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.final_schedule.rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.overrides_subschedule` | object | | Same fields as `schedule.final_schedule` above. | | `schedule.escalation_policies` | array of object | | An array of all of the escalation policies that uses this schedule. Read-only. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | An array of all of the users on the schedule. Read-only. | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.teams` | array of object | | An array of all of the teams on the schedule. Read-only. | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.next_oncall_for_user` | object | | | | `schedule.next_oncall_for_user.start` | string | | The start date for the User shift. Read-only. | | `schedule.next_oncall_for_user.end` | string | | The end date for the User shift. Read-only. | | `schedule.next_oncall_for_user.user` | object | | | | `schedule.next_oncall_for_user.user.id` | string | yes | Read-only. | | `schedule.next_oncall_for_user.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.next_oncall_for_user.user.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `schedule.next_oncall_for_user.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.next_oncall_for_user.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "schedule": { "name": "Daily Engineering Rotation", "type": "schedule", "time_zone": "America/New_York", "description": "Rotation schedule for engineering", "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": "PXPGF42", "type": "user_reference" } } ], "restrictions": [ { "type": "daily_restriction", "start_time_of_day": "08:00:00", "duration_seconds": 32400 } ] } ] } } ``` ## Response 200 What the schedule will look like if posted. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | Same fields as `schedule` above. | Example: Response Example ```json { "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": [], "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": [] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/delete-schedule # Delete a schedule `DELETE https://api.pagerduty.com/schedules/{id}` Delete an on-call schedule. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The schedule was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/delete-schedule-override # Delete an override `DELETE https://api.pagerduty.com/schedules/{id}/overrides/{override_id}` Remove an override. You cannot remove a past override. If the override start time is before the current time, but the end time is after the current time, the override will be truncated to the current time. If the override is truncated, the status code will be 200 OK, as opposed to a 204 No Content for a successful delete. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `override_id` | string | yes | The override ID on the schedule. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The override was truncated. ## Response 204 The override was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/get-schedule # Get a schedule `GET https://api.pagerduty.com/schedules/{id}` Show detailed information about a schedule, including entries for each layer. Scoped OAuth requires: `schedules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the schedule's time zone. | | `since` | string (date-time) | | 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. | | `until` | string (date-time) | | 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. | | `overflow` | boolean | | 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. For 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`: - 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`. - 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`. Default: `false`. | | `include_next_oncall_for_user` | string | | Specify an `user_id`, and the schedule list API will return information about this user's next on-call. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The schedule object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | | Read-only. | | `schedule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.type` | string | yes | The type of object being created. One of: `schedule`. Default: `schedule`. | | `schedule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers` | array of object | | A list of schedule layers. | | `schedule.schedule_layers[].id` | string | | | | `schedule.schedule_layers[].start` | string (date-time) | yes | The start time of this layer. | | `schedule.schedule_layers[].end` | string (date-time) | | The end time of this layer. If `null`, the layer does not end. | | `schedule.schedule_layers[].users` | array of object | yes | The ordered list of users on this layer. The position of the user on the list determines their order in the layer. | | `schedule.schedule_layers[].users[].user` | object | yes | | | `schedule.schedule_layers[].users[].user.id` | string | yes | Read-only. | | `schedule.schedule_layers[].users[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.schedule_layers[].users[].user.type` | string | yes | One of: `user_reference`. | | `schedule.schedule_layers[].users[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.schedule_layers[].users[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers[].restrictions` | array of object | | An array of restrictions for the layer. A restriction is a limit on which period of the day or week the schedule layer can accept assignments. Restrictions respect the `time_zone` parameter of the request. | | `schedule.schedule_layers[].restrictions[].type` | string | yes | Specify the types of `restriction`. One of: `daily_restriction`, `weekly_restriction`. | | `schedule.schedule_layers[].restrictions[].duration_seconds` | integer | yes | The duration of the restriction in seconds. | | `schedule.schedule_layers[].restrictions[].start_time_of_day` | string (partial-time) | yes | The start time in HH:mm:ss format. | | `schedule.schedule_layers[].restrictions[].start_day_of_week` | integer | | Only required for use with a `weekly_restriction` restriction type. The first day of the weekly rotation schedule as [ISO 8601 day](https://en.wikipedia.org/wiki/ISO_week_date) (1 is Monday, etc.) Minimum: 1. Maximum: 7. | | `schedule.schedule_layers[].rotation_virtual_start` | string (date-time) | yes | The effective start time of the layer. This can be before the start time of the schedule. | | `schedule.schedule_layers[].rotation_turn_length_seconds` | integer | yes | The duration of each on-call shift in seconds. | | `schedule.schedule_layers[].name` | string | | The name of the schedule layer. | | `schedule.schedule_layers[].rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.schedule_layers[].rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.schedule_layers[].rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.time_zone` | string (activesupport-time-zone) | yes | The time zone of the schedule. | | `schedule.name` | string | | The name of the schedule. | | `schedule.description` | string | | The description of the schedule. | | `schedule.final_schedule` | object | | | | `schedule.final_schedule.name` | string | yes | The name of the subschedule. Read-only. One of: `Final Schedule`, `Overrides`. | | `schedule.final_schedule.rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.final_schedule.rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.final_schedule.rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.overrides_subschedule` | object | | Same fields as `schedule.final_schedule` above. | | `schedule.escalation_policies` | array of object | | An array of all of the escalation policies that uses this schedule. Read-only. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | An array of all of the users on the schedule. Read-only. | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.teams` | array of object | | An array of all of the teams on the schedule. Read-only. | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.next_oncall_for_user` | object | | | | `schedule.next_oncall_for_user.start` | string | | The start date for the User shift. Read-only. | | `schedule.next_oncall_for_user.end` | string | | The end date for the User shift. Read-only. | | `schedule.next_oncall_for_user.user` | object | | | | `schedule.next_oncall_for_user.user.id` | string | yes | Read-only. | | `schedule.next_oncall_for_user.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.next_oncall_for_user.user.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `schedule.next_oncall_for_user.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.next_oncall_for_user.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "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" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/list-schedule-overrides # List overrides `GET https://api.pagerduty.com/schedules/{id}/overrides` List overrides for a given time range. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | yes | The start of the date range over which you want to search. | | `until` | string (date-time) | yes | The end of the date range over which you want to search. | | `editable` | boolean | | When this parameter is present, only editable overrides will be returned. The result will only include the id of the override if this parameter is present. Only future overrides are editable. | | `overflow` | boolean | | 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. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 201 The collection of override objects returned by the query. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `overrides` | array of object | yes | | | `overrides[].id` | string | | Read-only. | | `overrides[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `overrides[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `overrides[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `overrides[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `overrides[].start` | string (date-time) | yes | The start date and time for the override. | | `overrides[].end` | string (date-time) | yes | The end date and time for the override. | | `overrides[].user` | object | yes | | | `overrides[].user.id` | string | yes | Read-only. | | `overrides[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `overrides[].user.type` | string | yes | One of: `user_reference`. | | `overrides[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `overrides[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "overrides": [ { "id": "PQ47DCP", "start": "2012-07-01T00:00:00-04:00", "end": "2012-07-02T00:00:00-04:00", "user": { "id": "PEYSGVF", "type": "user_reference", "summary": "Aurelio Rice", "self": "https://api.pagerduty.com/users/PEYSGVF", "html_url": "https://subdomain.pagerduty.com/users/PEYSGVF" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/list-schedule-users # List users on call. `GET https://api.pagerduty.com/schedules/{id}/users` List all of the users on call in a given schedule for a given time range. A Schedule determines the time periods that users are On-Call. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `since` | string (date-time) | | The start of the date range over which you want to search. | | `until` | string (date-time) | | The end of the date range over which you want to search. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The users on the given schedule. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `users` | array of object | yes | Read-only. | | `users[].id` | string | | Read-only. | | `users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].name` | string | yes | The name of the user. Max length: 100. | | `users[].email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `users[].time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `users[].color` | string | | The schedule color. | | `users[].role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `users[].avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `users[].description` | string \| null | | The user's bio. | | `users[].invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `users[].job_title` | string | | The user's title. Max length: 100. | | `users[].created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `users[].teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `users[].teams[].id` | string | yes | Read-only. | | `users[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].teams[].type` | string | yes | One of: `team_reference`. | | `users[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `users[].contact_methods[].id` | string | yes | Read-only. | | `users[].contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `users[].contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `users[].notification_rules[].id` | string | yes | Read-only. | | `users[].notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `users[].notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `users[].web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "users": [ { "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": "Engineer based in HK", "invitation_sent": 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": "P8GRWKZ", "type": "assignment_notification_rule_reference", "summary": "Default", "self": "https://api.pagerduty.com/users/PAM4FGS/notification_rules/P8GRWKZ", "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" } ] }, { "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, "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" } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/list-schedules # List schedules `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `include[]` | string | | Array of additional details to include. One of: `schedule_layers`, `overrides_subschedule`, `final_schedule`. Items must be unique. | | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the current user's time zone and then the account's time zone. | | `include_next_oncall_for_user` | string | | Specify an `user_id`, and the schedule list API will return information about this user's next on-call. | | `since` | string (date-time) | | 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. | | `until` | string (date-time) | | 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. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of schedule objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `schedules` | array of object | yes | | | `schedules[].id` | string | | Read-only. | | `schedules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].type` | string | yes | The type of object being created. One of: `schedule`. Default: `schedule`. | | `schedules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedules[].schedule_layers` | array of object | | A list of schedule layers. | | `schedules[].schedule_layers[].id` | string | | | | `schedules[].schedule_layers[].start` | string (date-time) | yes | The start time of this layer. | | `schedules[].schedule_layers[].end` | string (date-time) | | The end time of this layer. If `null`, the layer does not end. | | `schedules[].schedule_layers[].users` | array of object | yes | The ordered list of users on this layer. The position of the user on the list determines their order in the layer. | | `schedules[].schedule_layers[].users[].user` | object | yes | | | `schedules[].schedule_layers[].users[].user.id` | string | yes | Read-only. | | `schedules[].schedule_layers[].users[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].schedule_layers[].users[].user.type` | string | yes | One of: `user_reference`. | | `schedules[].schedule_layers[].users[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].schedule_layers[].users[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedules[].schedule_layers[].restrictions` | array of object | | An array of restrictions for the layer. A restriction is a limit on which period of the day or week the schedule layer can accept assignments. Restrictions respect the `time_zone` parameter of the request. | | `schedules[].schedule_layers[].restrictions[].type` | string | yes | Specify the types of `restriction`. One of: `daily_restriction`, `weekly_restriction`. | | `schedules[].schedule_layers[].restrictions[].duration_seconds` | integer | yes | The duration of the restriction in seconds. | | `schedules[].schedule_layers[].restrictions[].start_time_of_day` | string (partial-time) | yes | The start time in HH:mm:ss format. | | `schedules[].schedule_layers[].restrictions[].start_day_of_week` | integer | | Only required for use with a `weekly_restriction` restriction type. The first day of the weekly rotation schedule as [ISO 8601 day](https://en.wikipedia.org/wiki/ISO_week_date) (1 is Monday, etc.) Minimum: 1. Maximum: 7. | | `schedules[].schedule_layers[].rotation_virtual_start` | string (date-time) | yes | The effective start time of the layer. This can be before the start time of the schedule. | | `schedules[].schedule_layers[].rotation_turn_length_seconds` | integer | yes | The duration of each on-call shift in seconds. | | `schedules[].schedule_layers[].name` | string | | The name of the schedule layer. | | `schedules[].schedule_layers[].rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedules[].schedule_layers[].rendered_schedule_entries[].user` | object | | Same fields as `schedules[].schedule_layers[].users[].user` above. | | `schedules[].schedule_layers[].rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedules[].schedule_layers[].rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedules[].schedule_layers[].rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedules[].time_zone` | string (activesupport-time-zone) | yes | The time zone of the schedule. | | `schedules[].name` | string | | The name of the schedule. | | `schedules[].description` | string | | The description of the schedule. | | `schedules[].final_schedule` | object | | | | `schedules[].final_schedule.name` | string | yes | The name of the subschedule. Read-only. One of: `Final Schedule`, `Overrides`. | | `schedules[].final_schedule.rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedules[].final_schedule.rendered_schedule_entries[].user` | object | | Same fields as `schedules[].schedule_layers[].users[].user` above. | | `schedules[].final_schedule.rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedules[].final_schedule.rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedules[].final_schedule.rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedules[].overrides_subschedule` | object | | Same fields as `schedules[].final_schedule` above. | | `schedules[].escalation_policies` | array of object | | An array of all of the escalation policies that uses this schedule. Read-only. | | `schedules[].escalation_policies[].id` | string | yes | Read-only. | | `schedules[].escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedules[].escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedules[].users` | array of object | | An array of all of the users on the schedule. Read-only. | | `schedules[].users[].id` | string | yes | Read-only. | | `schedules[].users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].users[].type` | string | yes | One of: `user_reference`. | | `schedules[].users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedules[].teams` | array of object | | An array of all of the teams on the schedule. Read-only. | | `schedules[].teams[].id` | string | yes | Read-only. | | `schedules[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].teams[].type` | string | yes | One of: `team_reference`. | | `schedules[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedules[].next_oncall_for_user` | object | | | | `schedules[].next_oncall_for_user.start` | string | | The start date for the User shift. Read-only. | | `schedules[].next_oncall_for_user.end` | string | | The end date for the User shift. Read-only. | | `schedules[].next_oncall_for_user.user` | object | | | | `schedules[].next_oncall_for_user.user.id` | string | yes | Read-only. | | `schedules[].next_oncall_for_user.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedules[].next_oncall_for_user.user.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `schedules[].next_oncall_for_user.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedules[].next_oncall_for_user.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Basic Example ```json { "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 } ``` Example: With Schedule Layers Included ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/list-schedules-audit-records # List audit records for a schedule `GET https://api.pagerduty.com/schedules/{id}/audit/records` The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PD_ASSIGN_TEAM_TO_SCHEDULE", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_TEAM123", "summary": "Devops", "type": "team_reference", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" } ], "name": "teams" } ], "resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, "execution_context": { "request_id": "13a1c0c3-545c-4ebb-4115-662fff9d8ad" }, "execution_time": "2021-01-05T16:25:41.324Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, { "id": "PD_CREATE_SCHEDULE", "action": "create", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "name", "value": "DevOps Schedule" }, { "name": "description", "value": "Our DevOps Team Schedule" }, { "name": "time_zone", "value": "America/New_York" } ], "resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } }, "execution_context": { "request_id": "13a1c0c3-545c-4ebb-4115-662fff9d8ad" }, "execution_time": "2021-01-05T16:25:41.315Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_SCHEDULE_ID", "summary": "DevOps Schedule", "type": "schedule_reference", "self": "https://api.pagerduty.com/schedules/PD_SCHEDULE_ID", "html_url": "https://mydomain.pagerduty.com/schedules/PD_SCHEDULE_ID" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/schedules/update-schedule # Update a schedule `PUT https://api.pagerduty.com/schedules/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#schedules) Scoped OAuth requires: `schedules.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `overflow` | boolean | | 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. For 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`: - 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`. - 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`. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The schedule to be updated. | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | | | `schedule.id` | string | | Read-only. | | `schedule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.type` | string | yes | The type of object being created. One of: `schedule`. Default: `schedule`. | | `schedule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers` | array of object | | A list of schedule layers. | | `schedule.schedule_layers[].id` | string | | | | `schedule.schedule_layers[].start` | string (date-time) | yes | The start time of this layer. | | `schedule.schedule_layers[].end` | string (date-time) | | The end time of this layer. If `null`, the layer does not end. | | `schedule.schedule_layers[].users` | array of object | yes | The ordered list of users on this layer. The position of the user on the list determines their order in the layer. | | `schedule.schedule_layers[].users[].user` | object | yes | | | `schedule.schedule_layers[].users[].user.id` | string | yes | Read-only. | | `schedule.schedule_layers[].users[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.schedule_layers[].users[].user.type` | string | yes | One of: `user_reference`. | | `schedule.schedule_layers[].users[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.schedule_layers[].users[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.schedule_layers[].restrictions` | array of object | | An array of restrictions for the layer. A restriction is a limit on which period of the day or week the schedule layer can accept assignments. Restrictions respect the `time_zone` parameter of the request. | | `schedule.schedule_layers[].restrictions[].type` | string | yes | Specify the types of `restriction`. One of: `daily_restriction`, `weekly_restriction`. | | `schedule.schedule_layers[].restrictions[].duration_seconds` | integer | yes | The duration of the restriction in seconds. | | `schedule.schedule_layers[].restrictions[].start_time_of_day` | string (partial-time) | yes | The start time in HH:mm:ss format. | | `schedule.schedule_layers[].restrictions[].start_day_of_week` | integer | | Only required for use with a `weekly_restriction` restriction type. The first day of the weekly rotation schedule as [ISO 8601 day](https://en.wikipedia.org/wiki/ISO_week_date) (1 is Monday, etc.) Minimum: 1. Maximum: 7. | | `schedule.schedule_layers[].rotation_virtual_start` | string (date-time) | yes | The effective start time of the layer. This can be before the start time of the schedule. | | `schedule.schedule_layers[].rotation_turn_length_seconds` | integer | yes | The duration of each on-call shift in seconds. | | `schedule.schedule_layers[].name` | string | | The name of the schedule layer. | | `schedule.schedule_layers[].rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.schedule_layers[].rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.schedule_layers[].rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.schedule_layers[].rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.time_zone` | string (activesupport-time-zone) | yes | The time zone of the schedule. | | `schedule.name` | string | | The name of the schedule. | | `schedule.description` | string | | The description of the schedule. | | `schedule.final_schedule` | object | | | | `schedule.final_schedule.name` | string | yes | The name of the subschedule. Read-only. One of: `Final Schedule`, `Overrides`. | | `schedule.final_schedule.rendered_schedule_entries` | array of object | | This is a list of entries on the computed layer for the current time range. Since or until must be set in order for this field to be populated. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].user` | object | | Same fields as `schedule.schedule_layers[].users[].user` above. | | `schedule.final_schedule.rendered_schedule_entries[].start` | string (date-time) | yes | The start time of this entry. Read-only. | | `schedule.final_schedule.rendered_schedule_entries[].end` | string (date-time) | yes | The end time of this entry. If null, the entry does not end. Read-only. | | `schedule.final_schedule.rendered_coverage_percentage` | number | | The percentage of the time range covered by this layer. Returns null unless since or until are set. Read-only. | | `schedule.overrides_subschedule` | object | | Same fields as `schedule.final_schedule` above. | | `schedule.escalation_policies` | array of object | | An array of all of the escalation policies that uses this schedule. Read-only. | | `schedule.escalation_policies[].id` | string | yes | Read-only. | | `schedule.escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.escalation_policies[].type` | string | yes | One of: `escalation_policy_reference`. | | `schedule.escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.users` | array of object | | An array of all of the users on the schedule. Read-only. | | `schedule.users[].id` | string | yes | Read-only. | | `schedule.users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.users[].type` | string | yes | One of: `user_reference`. | | `schedule.users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.teams` | array of object | | An array of all of the teams on the schedule. Read-only. | | `schedule.teams[].id` | string | yes | Read-only. | | `schedule.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.teams[].type` | string | yes | One of: `team_reference`. | | `schedule.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `schedule.next_oncall_for_user` | object | | | | `schedule.next_oncall_for_user.start` | string | | The start date for the User shift. Read-only. | | `schedule.next_oncall_for_user.end` | string | | The end date for the User shift. Read-only. | | `schedule.next_oncall_for_user.user` | object | | | | `schedule.next_oncall_for_user.user.id` | string | yes | Read-only. | | `schedule.next_oncall_for_user.user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `schedule.next_oncall_for_user.user.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `schedule.next_oncall_for_user.user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `schedule.next_oncall_for_user.user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "schedule": { "name": "Daily Engineering Rotation", "type": "schedule", "time_zone": "America/New_York", "description": "Rotation schedule for engineering", "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": "PXPGF42", "type": "user_reference" } } ], "restrictions": [ { "type": "daily_restriction", "start_time_of_day": "08:00:00", "duration_seconds": 32400 } ] } ] } } ``` ## Response 200 The updated schedule. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `schedule` | object | yes | Same fields as `schedule` above. | Example: Response Example ```json { "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": [] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/create-service-custom-field # Create a Field `POST https://api.pagerduty.com/services/custom_fields` Creates a new Custom Field for Services, along with the Field Options if provided. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Details of the custom field to be created. | | `field.data_type` | string | yes | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | yes | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `field.field_options` | array of object | | | | `field.field_options[].data` | object | yes | The data content of the field option. | | `field.field_options[].data.data_type` | string | yes | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | yes | The value of the field option. Must be unique within the field. Max length: 200. | | `field.field_type` | string | yes | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.name` | string | yes | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | Example: Example: With field_options and single-value ```json { "field": { "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_options": [ { "data": { "data_type": "string", "value": "production" } }, { "data": { "data_type": "string", "value": "staging" } }, { "data": { "data_type": "string", "value": "development" } } ], "field_type": "single_value_fixed", "name": "environment" } } ``` Example: Example: With field_options and multi-value ```json { "field": { "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_options": [ { "data": { "data_type": "string", "value": "us-east-1" } }, { "data": { "data_type": "string", "value": "us-west-1" } }, { "data": { "data_type": "string", "value": "eu-west-1" } }, { "data": { "data_type": "string", "value": "ap-southeast-1" } } ], "field_type": "multi_value_fixed", "name": "supported_regions" } } ``` Example: Example: Without field_options ```json { "field": { "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "name": "team_owner" } } ``` ## Response 201 The field object created, along with the Field Options if provided. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Details of the custom field. | | `field.created_at` | string (date-time) | | The date/time the object was created at. | | `field.data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `field.field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. These options are returned only if the `include[]` parameter specifies `field_options`. | | `field.field_options[].created_at` | string (date-time) | | The date/time the object was created at. | | `field.field_options[].data` | object | | | | `field.field_options[].data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | | Max length: 200. | | `field.field_options[].id` | string | | The ID of the resource. | | `field.field_options[].type` | string | | One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | | The date/time the object was updated at. | | `field.field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | | The ID of the resource. | | `field.name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Example: With field_options and single-value ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "development" }, "id": "OPT3", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` Example: Example: With field_options and multi-value ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-east-1" }, "id": "OPT4", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-west-1" }, "id": "OPT5", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "eu-west-1" }, "id": "OPT6", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "ap-southeast-1" }, "id": "OPT7", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "multi_value_fixed", "id": "ABCDEF2", "name": "supported_regions", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF2", "summary": "Supported Regions", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` Example: Example: Without field_options ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "id": "ABCDEF3", "name": "team_owner", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF3", "summary": "Team Owner", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/create-service-custom-field-option # Create a Field Option `POST https://api.pagerduty.com/services/custom_fields/{field_id}/field_options` Create a new option for the given field. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | An option for a custom field. Can only be applied to fields with a `field_type` of `single_value_fixed` or `multi_value_fixed`. | | `field_option.data` | object | yes | The data content of the field option. | | `field_option.data.data_type` | string | yes | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | The value of the field option. Must be unique within the field. Max length: 200. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "production" } } } ``` ## Response 201 The field option created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | | | | `field_option.created_at` | string (date-time) | | The date/time the object was created at. | | `field_option.data` | object | | | | `field_option.data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | | Max length: 200. | | `field_option.id` | string | | The ID of the resource. | | `field_option.type` | string | | One of: `field_option`. | | `field_option.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example ```json { "field_option": { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/delete-service-custom-field # Delete a Field `DELETE https://api.pagerduty.com/services/custom_fields/{field_id}` Delete a Custom Field from Services. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The field was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/delete-service-custom-field-option # Delete a Field Option `DELETE https://api.pagerduty.com/services/custom_fields/{field_id}/field_options/{field_option_id}` Delete a field option. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | | `field_option_id` | string | yes | The ID of the field option. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The field option was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/get-service-custom-field # Get a Field `GET https://api.pagerduty.com/services/custom_fields/{field_id}` Show detailed information about a Custom Field for Services. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The field requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | | Details of the custom field. | | `field.created_at` | string (date-time) | | The date/time the object was created at. | | `field.data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `field.field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. These options are returned only if the `include[]` parameter specifies `field_options`. | | `field.field_options[].created_at` | string (date-time) | | The date/time the object was created at. | | `field.field_options[].data` | object | | | | `field.field_options[].data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | | Max length: 200. | | `field.field_options[].id` | string | | The ID of the resource. | | `field.field_options[].type` | string | | One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | | The date/time the object was updated at. | | `field.field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | | The ID of the resource. | | `field.name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example (Default) ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` Example: Response Example (With field_options included) ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "development" }, "id": "OPT3", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/get-service-custom-field-option # Get a Field Option `GET https://api.pagerduty.com/services/custom_fields/{field_id}/field_options/{field_option_id}` Get a field option for a given field. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | | `field_option_id` | string | yes | The ID of the field option. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requested field option. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | | | | `field_option.created_at` | string (date-time) | | The date/time the object was created at. | | `field_option.data` | object | | | | `field_option.data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | | Max length: 200. | | `field_option.id` | string | | The ID of the resource. | | `field_option.type` | string | | One of: `field_option`. | | `field_option.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example ```json { "field_option": { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/list-service-custom-field-options # List Field Options `GET https://api.pagerduty.com/services/custom_fields/{field_id}/field_options` List all options for a given field. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 List of field options. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_options` | array of object | | | | `field_options[].created_at` | string (date-time) | | The date/time the object was created at. | | `field_options[].data` | object | | | | `field_options[].data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_options[].data.value` | string | | Max length: 200. | | `field_options[].id` | string | | The ID of the resource. | | `field_options[].type` | string | | One of: `field_option`. | | `field_options[].updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example ```json { "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "development" }, "id": "OPT3", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/list-service-custom-fields # List Fields `GET https://api.pagerduty.com/services/custom_fields` List Custom Fields available for Services. Scoped OAuth requires: `custom_fields.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `field_options`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of fields. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `fields` | array of object | | | | `fields[].created_at` | string (date-time) | | The date/time the object was created at. | | `fields[].data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `fields[].description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `fields[].display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `fields[].enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `fields[].field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. These options are returned only if the `include[]` parameter specifies `field_options`. | | `fields[].field_options[].created_at` | string (date-time) | | The date/time the object was created at. | | `fields[].field_options[].data` | object | | | | `fields[].field_options[].data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `fields[].field_options[].data.value` | string | | Max length: 200. | | `fields[].field_options[].id` | string | | The ID of the resource. | | `fields[].field_options[].type` | string | | One of: `field_option`. | | `fields[].field_options[].updated_at` | string (date-time) | | The date/time the object was updated at. | | `fields[].field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `fields[].id` | string | | The ID of the resource. | | `fields[].name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `fields[].self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | | `fields[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `fields[].type` | string | | Read-only. One of: `field`. | | `fields[].updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example (Default) ```json { "fields": [ { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_type": "multi_value_fixed", "id": "ABCDEF2", "name": "supported_regions", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF2", "summary": "Supported Regions", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "id": "ABCDEF3", "name": "team_owner", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF3", "summary": "Team Owner", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } ] } ``` Example: Response Example (With field_options included) ```json { "fields": [ { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The environment that the service operates in", "display_name": "Environment", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "development" }, "id": "OPT3", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Environment", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The regions where this service is deployed", "display_name": "Supported Regions", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-east-1" }, "id": "OPT4", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "us-west-1" }, "id": "OPT5", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "eu-west-1" }, "id": "OPT6", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "ap-southeast-1" }, "id": "OPT7", "type": "field_option", "updated_at": "2023-01-01T00:00:00Z" } ], "field_type": "multi_value_fixed", "id": "ABCDEF2", "name": "supported_regions", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF2", "summary": "Supported Regions", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The team that owns this service", "display_name": "Team Owner", "enabled": true, "field_type": "single_value", "id": "ABCDEF3", "name": "team_owner", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF3", "summary": "Team Owner", "type": "custom_fields_field", "updated_at": "2023-01-01T00:00:00Z" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/update-service-custom-field # Update a Field `PUT https://api.pagerduty.com/services/custom_fields/{field_id}` Update a Custom Field for Services. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field` | object | yes | Details of the custom field to be updated. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `field.field_options` | array of object | | List of field options to update, insert or delete. This field supports several behaviors: - Empty array: Deletes all field options - Omitting the `field_options` array entirely: Preserves all existing options - Not listing an existing option: Deletes that option (unless it's the current default value) | | `field.field_options[].data` | object | yes | The data content of the field option. | | `field.field_options[].data.data_type` | string | yes | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | yes | The value of the field option. Must be unique within the field. Max length: 200. | | `field.field_options[].id` | string | | The unique identifier of the field option. How this field is used determines the behavior: - When included with a valid `id`: Updates the corresponding existing field option - When omitted or null: Creates a new field option. | Example: Update Field Example - Basic Properties ```json { "field": { "description": "The production environment where this service is deployed", "display_name": "Production Environment", "enabled": true } } ``` Example: Update Field Example - With Field Options ```json { "field": { "description": "The production environment where this service is deployed", "display_name": "Production Environment", "enabled": true, "field_options": [ { "data": { "data_type": "string", "value": "production" }, "id": "OPT1" }, { "data": { "data_type": "string", "value": "staging-new" }, "id": "OPT2" }, { "data": { "data_type": "string", "value": "development-new" } } ] } } ``` ## Response 200 The field object updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field` | object | | Details of the custom field. | | `field.created_at` | string (date-time) | | The date/time the object was created at. | | `field.data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `field.description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `field.display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `field.enabled` | boolean | | Whether the field is enabled. One of: `true`, `false`. | | `field.field_options` | array of object | | The options for the custom field. Applies only to `single_value_fixed` and `multi_value_fixed` field types. These options are returned only if the `include[]` parameter specifies `field_options`. | | `field.field_options[].created_at` | string (date-time) | | The date/time the object was created at. | | `field.field_options[].data` | object | | | | `field.field_options[].data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field.field_options[].data.value` | string | | Max length: 200. | | `field.field_options[].id` | string | | The ID of the resource. | | `field.field_options[].type` | string | | One of: `field_option`. | | `field.field_options[].updated_at` | string (date-time) | | The date/time the object was updated at. | | `field.field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `field.id` | string | | The ID of the resource. | | `field.name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `field.self` | string \| null (url) | | The API show URL at which the object is accessible. Read-only. | | `field.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `display_name`. Read-only. | | `field.type` | string | | Read-only. One of: `field`. | | `field.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example ```json { "field": { "created_at": "2023-01-01T00:00:00Z", "data_type": "string", "description": "The production environment where this service is deployed", "display_name": "Production Environment", "enabled": true, "field_options": [ { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "production" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-02T00:00:00Z" }, { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "staging-new" }, "id": "OPT2", "type": "field_option", "updated_at": "2023-01-02T00:00:00Z" }, { "created_at": "2023-01-02T00:00:00Z", "data": { "data_type": "string", "value": "development-new" }, "id": "OPT4", "type": "field_option", "updated_at": "2023-01-02T00:00:00Z" } ], "field_type": "single_value_fixed", "id": "ABCDEF1", "name": "environment", "self": "https://api.pagerduty.com/services/custom_fields/ABCDEF1", "summary": "Production Environment", "type": "custom_fields_field", "updated_at": "2023-01-02T00:00:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-custom-fields/update-service-custom-field-option # Update a Field Option `PUT https://api.pagerduty.com/services/custom_fields/{field_id}/field_options/{field_option_id}` Update a field option for a given field. Scoped OAuth requires: `custom_fields.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `field_id` | string | yes | The ID of the field. | | `field_option_id` | string | yes | The ID of the field option. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | yes | An option for a custom field. Can only be applied to fields with a `field_type` of `single_value_fixed` or `multi_value_fixed`. | | `field_option.data` | object | yes | The data content of the field option. | | `field_option.data.data_type` | string | yes | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | yes | The value of the field option. Must be unique within the field. Max length: 200. | Example: Request Example ```json { "field_option": { "data": { "data_type": "string", "value": "prod" } } } ``` ## Response 200 The field option updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `field_option` | object | | | | `field_option.created_at` | string (date-time) | | The date/time the object was created at. | | `field_option.data` | object | | | | `field_option.data.data_type` | string | | The kind of data represented by this option. Must match the Field's `data_type`. One of: `string`. | | `field_option.data.value` | string | | Max length: 200. | | `field_option.id` | string | | The ID of the resource. | | `field_option.type` | string | | One of: `field_option`. | | `field_option.updated_at` | string (date-time) | | The date/time the object was updated at. | Example: Response Example ```json { "field_option": { "created_at": "2023-01-01T00:00:00Z", "data": { "data_type": "string", "value": "prod" }, "id": "OPT1", "type": "field_option", "updated_at": "2023-01-02T00:00:00Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-dependencies/create-service-dependency # Associate service dependencies `POST https://api.pagerduty.com/service_dependencies/associate` Create new dependencies between two services. Business services model capabilities that span multiple technical services and that may be owned by several different teams. A service can have a maximum of 2,000 dependencies with a depth limit of 100. If the limit is reached, the API will respond with an error. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all service dependencies to be created. | | `relationships[].supporting_service` | object | | The reference to the service that supports the dependent service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the supporting service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | Example: Request Example ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "service" }, "dependent_service": { "id": "P99DJ6", "type": "business_service" } }, { "supporting_service": { "id": "DT93K1", "type": "business_service" }, "dependent_service": { "id": "RS34D9", "type": "service" } } ] } ``` ## Response 200 An array of service relationships that were successfully associated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all the technical service's dependencies. | | `relationships[].supporting_service` | object | | The reference to the service that supports the technical service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the technical service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | | `relationships[].id` | string | | | | `relationships[].type` | string | | | Example: Response Example ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "technical_service_reference" }, "dependent_service": { "id": "P99DJ6", "type": "business_service_reference" }, "id": "DQVP7E6G0E8AC3NR", "type": "service_dependency" }, { "supporting_service": { "id": "DT93K1", "type": "business_service_reference" }, "dependent_service": { "id": "RS34D9", "type": "technical_service_reference" }, "id": "D3PG0QVACE87RNE6", "type": "service_dependency" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-dependencies/delete-service-dependency # Disassociate service dependencies `POST https://api.pagerduty.com/service_dependencies/disassociate` Disassociate dependencies between two services. Business services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all service dependencies to be deleted. | | `relationships[].supporting_service` | object | | The reference to the service that supports the dependent service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the supporting service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | Example: Request Example ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "service" }, "dependent_service": { "id": "P99DJ6", "type": "business_service" } }, { "supporting_service": { "id": "DT93K1", "type": "business_service" }, "dependent_service": { "id": "RS34D9", "type": "service" } } ] } ``` ## Response 200 An array of service relationships that were successfully disassociated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all the technical service's dependencies. | | `relationships[].supporting_service` | object | | The reference to the service that supports the technical service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the technical service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | | `relationships[].id` | string | | | | `relationships[].type` | string | | | Example: Example Response ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "technical_service_reference" }, "dependent_service": { "id": "P99DJ6", "type": "business_service_reference" }, "id": "DQVP7E6G0E8AC3NR", "type": "service_dependency" }, { "supporting_service": { "id": "DT93K1", "type": "business_service_reference" }, "dependent_service": { "id": "RS34D9", "type": "technical_service_reference" }, "id": "D3PG0QVACE87RNE6", "type": "service_dependency" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-dependencies/get-business-service-service-dependencies # Get Business Service dependencies `GET https://api.pagerduty.com/service_dependencies/business_services/{id}` Get all immediate dependencies of any Business Service. Business Services model capabilities that span multiple technical services and that may be owned by several different teams. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#business-services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of service relationships. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all the Business Service's dependencies. | | `relationships[].supporting_service` | object | | The reference to the service that supports the Business Service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the Business Service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | | `relationships[].id` | string | | | | `relationships[].type` | string | | | Example: Response Example ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "technical_service_reference" }, "dependent_service": { "id": "P99DJ6", "type": "business_service_reference" }, "id": "DQVP7E6G0E8AC3NR", "type": "service_dependency" }, { "supporting_service": { "id": "P99DJ6", "type": "business_service_reference" }, "dependent_service": { "id": "RS34D9", "type": "business_service_reference" }, "id": "D3PG0QVACE87RNE6", "type": "service_dependency" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/service-dependencies/get-technical-service-service-dependencies # Get technical service dependencies `GET https://api.pagerduty.com/service_dependencies/technical_services/{id}` Get all immediate dependencies of any technical service. Technical services are also known as `services`. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of service relationships. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `relationships` | array of object | | List of all the technical service's dependencies. | | `relationships[].supporting_service` | object | | The reference to the service that supports the technical service. | | `relationships[].supporting_service.id` | string | | | | `relationships[].supporting_service.type` | string | | | | `relationships[].dependent_service` | object | | The reference to the service that is dependent on the technical service. | | `relationships[].dependent_service.id` | string | | | | `relationships[].dependent_service.type` | string | | | | `relationships[].id` | string | | | | `relationships[].type` | string | | | Example: Response Example ```json { "relationships": [ { "supporting_service": { "id": "P7AD56", "type": "technical_service_reference" }, "dependent_service": { "id": "P99DJ6", "type": "business_service_reference" }, "id": "DQVP7E6G0E8AC3NR", "type": "service_dependency" }, { "supporting_service": { "id": "R87DK4", "type": "technical_service_reference" }, "dependent_service": { "id": "P7AD56", "type": "technical_service_reference" }, "id": "D3PG0QVACE87RNE6", "type": "service_dependency" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/convert-service-event-rules-to-event-orchestration # Convert a Service's Event Rules into Event Orchestration Rules `POST https://api.pagerduty.com/services/{id}/rules/convert` Convert this Service's Event Rules into functionally equivalent Event Orchestration Rules. Sending a request to this API endpoint has several effects: 1. Automatically creates Event Orchestration Rules for this Service that will behave identically as this Service's currently configured Event Rules. 2. Makes all existing Event Rules for this Service read-only. All future updates need to be made via the newly created Event Orchestration rules. Sending a request to this API endpoint will **not** change how future events will be processed. If past events for this Service have been evaluated via Event Rules then new events sent to this Service will also continue to be evaluated via the (now read-only) Event Rules. To change this Service so that new events start being evaluated via the newly created Event Orchestration Rules use the [Update the Service Orchestration active status for a Service API](https://docs.pagerduty.com/developer/api/reference/rest/event-orchestrations/update-orch-active-status). > ### End-of-life > Event Rules will end-of-life soon. We highly recommend that you use this API to [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Event Orchestration Rules were successfully created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `convert_status` | string | | Did PagerDuty successfully create equivalent Event Orchestration rules. Read-only. | | `converted_to` | string (url) | | the API URL at which the newly created Event Orchestration rules are accessible. Read-only. | Example: Response Example ```json { "convert_status": "completed", "converted_to": "https://api.pagerduty.com/event_orchestrations/service/PC2D9ML" } ``` ## Response 400 Could not create equivalent Event Orchestration Rules based on the Service's current Event Rules ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of object | | Read-only. | | `error.errors[].rule_id` | string | | The ID of the Service Event Rule that couldn't be successfully converted. Read-only. | | `error.errors[].position` | integer | | The position of the Service Event Rule that couldn't be successfully converted. Read-only. | | `error.errors[].messages` | array of string | | Human friendly explanations of why this Event Rule couldn't be converted into an equivalent Event Orchestration Rule. Read-only. | Example: Response Example ```json { "error": { "message": "Unable to convert given Ruleset to an Event Orchestration", "errors": [ { "rule_id": "693cdcd1-ecfd-4064-a834-5cb28a74c060", "position": 0, "messages": [ "Unable to convert a rule that has a `time_frame` with both `active_between` and `scheduled_weekly` settings." ] }, { "rule_id": "9f6896c0-b435-401f-b25f-62e145d9ccf4", "position": 5, "messages": [ "Unable to convert `actions.extractions`; Should have a most 25 extractions but this rule has 42 extractions." ] } ] } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/create-service # Create a service `POST https://api.pagerduty.com/services` Create a new service. If `status` is included in the request, it must have a value of `active` when creating a new service. If a different status is required, make a second request to update the service. A service may represent an application, component, or team you wish to open incidents against. There is a limit of 25,000 services per account. If the limit is reached, the API will respond with an error. There is also a limit of 100,000 open Incidents per Service. If the limit is reached and `auto_resolve_timeout` is disabled (set to 0 or null), the `auto_resolve_timeout` property will automatically be set to 84600 (1 day). For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The service to be created | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | | | `service.id` | string | | Read-only. | | `service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.type` | string | yes | The type of object being created. One of: `service`. Default: `service`. | | `service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.name` | string | | The name of the service. | | `service.description` | string | | The user-provided description of the service. | | `service.auto_resolve_timeout` | integer | | Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `service.acknowledgement_timeout` | integer | | Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `service.created_at` | string (date-time) | | The date/time when this service was created. Read-only. | | `service.status` | string | | The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `service.last_incident_timestamp` | string (date-time) | | The date/time when the most recent incident was created for this service. Read-only. | | `service.escalation_policy` | object | yes | | | `service.escalation_policy.id` | string | yes | Read-only. | | `service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.response_play` | | | Response plays associated with this service. **Deprecated.** | | `service.teams` | array of object | | The set of teams associated with this service. Read-only. | | `service.teams[].id` | string | yes | Read-only. | | `service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.teams[].type` | string | yes | One of: `team_reference`. | | `service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.integrations` | array of object | | An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `service.integrations[].id` | string | yes | Read-only. | | `service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.incident_urgency_rule` | object | | | | `service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.during_support_hours` | object | | | | `service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `service.incident_urgency_rule.during_support_hours` above. | | `service.support_hours` | object | | | | `service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `service.support_hours.days_of_week` | array of integer | | Read-only. | | `service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `service.scheduled_actions` | array of object | | An array containing scheduled actions for the service. | | `service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `service.addons` | array of object | | The array of Add-ons associated with this service. Read-only. | | `service.addons[].id` | string | yes | Read-only. | | `service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.addons[].src` | string (url) | | The URL source of the Addon. | | `service.addons[].name` | string | | The user entered name of the Addon. | | `service.alert_creation` | string | | Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `service.alert_grouping_parameters` | one of: object \| object | | Alert Grouping Parameters. **Deprecated.** | | `service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `service.alert_grouping` | string | | Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `service.alert_grouping_timeout` | integer | | The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `service.auto_pause_notifications_parameters` | object | | Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | Example: Request Example ```json { "service": { "type": "service", "name": "My Web App", "description": "My cool web application that does things.", "auto_resolve_timeout": 14400, "acknowledgement_timeout": 600, "status": "active", "escalation_policy": { "id": "PWIP6CQ", "type": "escalation_policy_reference" }, "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" } ], "alert_creation": "create_alerts_and_incidents", "alert_grouping_parameters": { "type": "time", "config": { "timeout": 2 } }, "auto_pause_notifications_parameters": { "enabled": true, "timeout": 300 } } } ``` ## Response 201 The service that was created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | Same fields as `service` above. | Example: Response Example ```json { "service": { "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", "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 } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/create-service-event-rule # Create an Event Rule on a Service `POST https://api.pagerduty.com/services/{id}/rules` Create a new Event Rule on a Service. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | yes | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule on the Service. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching Event Rule is found or the end of the list is reached. | | `rule.actions` | object | | When an event matches this Event Rule, the actions that will be taken to change the resulting Alert and Incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | Example: Request Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "class" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was modified by an Event Rule" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "custom_details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 201 The Event Rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | Same fields as `rule` above. | Example: Response Example ```json { "ruleset": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "self": "https://api.pagerduty.com/services/PI2KBWI/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "class" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was modified by an Event Rule" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "custom_details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/create-service-integration # Create a new integration `POST https://api.pagerduty.com/services/{id}/integrations` Create a new integration belonging to a Service. A service may represent an application, component, or team you wish to open incidents against. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The integration to be created | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | | | `integration.id` | string | | Read-only. | | `integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.type` | string | | One of: `aws_cloudwatch_inbound_integration`, `cloudkick_inbound_integration`, `event_transformer_api_inbound_integration`, `generic_email_inbound_integration`, `generic_events_api_inbound_integration`, `keynote_inbound_integration`, `nagios_inbound_integration`, `pingdom_inbound_integration`, `sql_monitor_inbound_integration`, `events_api_v2_inbound_integration`. | | `integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.name` | string | | The name of this integration. | | `integration.service` | object | | | | `integration.service.id` | string | yes | Read-only. | | `integration.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.service.type` | string | yes | One of: `service_reference`. | | `integration.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.created_at` | string (date-time) | | The date/time when this integration was created. Read-only. | | `integration.vendor` | object | | | | `integration.vendor.id` | string | yes | Read-only. | | `integration.vendor.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.vendor.type` | string | yes | One of: `vendor_reference`. | | `integration.vendor.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.vendor.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.integration_email` | string | | Specify for generic_email_inbound_integration. Must be set to an email address @your-subdomain.pagerduty.com. | | `integration.email_incident_creation` | string | | Specify for generic_email_inbound_integration. One of: `on_new_email`, `on_new_email_subject`, `only_if_no_open_incidents`, `use_rules`. | | `integration.email_filter_mode` | string | | Specify for generic_email_inbound_integration. May override email_incident_creation. One of: `all-email`, `or-rules-email`, `and-rules-email`. | | `integration.email_parsers` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_parsers[].action` | string | yes | One of: `trigger`, `resolve`. | | `integration.email_parsers[].match_predicate` | object | yes | | | `integration.email_parsers[].match_predicate.type` | string | yes | One of: `all`, `any`, `not`, `contains`, `exactly`, `regex`. | | `integration.email_parsers[].match_predicate.matcher` | string | | Required if the type is `contains`, `exactly` or `regex`. Min length: 1. | | `integration.email_parsers[].match_predicate.part` | string | yes | The email field that will attempt to use the matcher expression. Required if the type is `contains`, `exactly` or `regex`. One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].match_predicate.children` | array of MatchPredicate (recursive) | yes | Additional matchers to be run. Must be not empty if the type is `all`, `any`, or `not`. | | `integration.email_parsers[].value_extractors` | array of object | | Additional values that will be pulled in to the Incident object. Exactly one value extractor must have a `value_name` of `incident_key`. Min items: 1. Items must be unique. | | `integration.email_parsers[].value_extractors[].type` | string | yes | One of: `entire`, `regex`, `between`. | | `integration.email_parsers[].value_extractors[].part` | string | yes | One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].value_extractors[].value_name` | string | yes | The field name to set in the Incident object. Exactly one must use the `value_name` of `incident_key` Min length: 1. | | `integration.email_parsers[].value_extractors[].regex` | string | | | | `integration.email_parsers[].value_extractors[].starts_after` | string | | | | `integration.email_parsers[].value_extractors[].ends_with` | string | | | | `integration.email_parsing_fallback` | string | | Specify for generic_email_inbound_integration. One of: `open_new_incident`, `discard`. | | `integration.email_filters` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_filters[].subject_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].subject_regex` | string | | Specify if subject_mode is set to match or no-match. | | `integration.email_filters[].body_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].body_regex` | string | | Specify if body_mode is set to match or no-match. | | `integration.email_filters[].from_email_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].from_email_regex` | string | | Specify if from_email_mode is set to match or no-match. | Example: Request Example for Email Integration ```json { "integration": { "type": "generic_email_inbound_integration", "name": "Email", "service": { "id": "PQL78HM", "type": "service_reference" }, "integration_email": "my-email-based-integration@subdomain.pagerduty.com", "vendor": { "type": "vendor_reference", "id": "PZD94QK" } } } ``` Example: Email Integration With Filters ```json { "integration": { "type": "generic_email_inbound_integration", "name": "Email with Filters", "integration_email": "your-service@subdomain.pd-staging.com", "email_incident_creation": "on_new_email_subject", "email_filter_mode": "or-rules-email", "email_parsers": [ { "action": "trigger", "match_predicate": { "type": "any", "matcher": "this thing", "part": "body", "children": [] }, "value_extractors": [ { "type": "entire", "part": "body", "value_name": "incident_key" } ] } ], "email_parsing_fallback": "discard", "email_filters": [ { "subject_mode": "match", "subject_regex": "alert", "body_mode": "match", "body_regex": "alert", "from_email_mode": "match", "from_email_regex": "alert" } ] } } ``` Example: Request Example for Events v2 Integration ```json { "integration": { "type": "events_api_v2_inbound_integration", "name": "Events V2", "service": { "id": "PQL78HM", "type": "service_reference" } } } ``` ## Response 201 The integration that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | Same fields as `integration` above. | Example: Response Example ```json { "integration": { "id": "PE1U9CH", "type": "generic_email_inbound_integration", "summary": "Email", "self": "https://api.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "html_url": "https://subdomain.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "name": "Email", "service": { "id": "PQL78HM", "type": "service_reference", "summary": "My Email-Based Integration", "self": "https://api.pagerduty.com/services/PQL78HM", "html_url": "https://subdomain.pagerduty.com/service-directory/PQL78HM" }, "created_at": "2015-10-14T13:33:02-07:00", "integration_email": "my-email-based-integration@subdomain.pagerduty.com" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/delete-service # Delete a service `DELETE https://api.pagerduty.com/services/{id}` Delete an existing service. Once the service is deleted, it will not be accessible from the web UI and new incidents won't be able to be created for this service. A service may represent an application, component, or team you wish to open incidents against. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The service was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/delete-service-event-rule # Delete an Event Rule from a Service `DELETE https://api.pagerduty.com/services/{id}/rules/{rule_id}` Delete an Event Rule from a Service. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Event Rule was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/get-service # Get a service `GET https://api.pagerduty.com/services/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `escalation_policies`, `teams`, `auto_pause_notifications_parameters`, `integrations`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The service requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | | | `service.id` | string | | Read-only. | | `service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.type` | string | yes | The type of object being created. One of: `service`. Default: `service`. | | `service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.name` | string | | The name of the service. | | `service.description` | string | | The user-provided description of the service. | | `service.auto_resolve_timeout` | integer | | Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `service.acknowledgement_timeout` | integer | | Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `service.created_at` | string (date-time) | | The date/time when this service was created. Read-only. | | `service.status` | string | | The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `service.last_incident_timestamp` | string (date-time) | | The date/time when the most recent incident was created for this service. Read-only. | | `service.escalation_policy` | object | yes | | | `service.escalation_policy.id` | string | yes | Read-only. | | `service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.response_play` | | | Response plays associated with this service. **Deprecated.** | | `service.teams` | array of object | | The set of teams associated with this service. Read-only. | | `service.teams[].id` | string | yes | Read-only. | | `service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.teams[].type` | string | yes | One of: `team_reference`. | | `service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.integrations` | array of object | | An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `service.integrations[].id` | string | yes | Read-only. | | `service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.incident_urgency_rule` | object | | | | `service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.during_support_hours` | object | | | | `service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `service.incident_urgency_rule.during_support_hours` above. | | `service.support_hours` | object | | | | `service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `service.support_hours.days_of_week` | array of integer | | Read-only. | | `service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `service.scheduled_actions` | array of object | | An array containing scheduled actions for the service. | | `service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `service.addons` | array of object | | The array of Add-ons associated with this service. Read-only. | | `service.addons[].id` | string | yes | Read-only. | | `service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.addons[].src` | string (url) | | The URL source of the Addon. | | `service.addons[].name` | string | | The user entered name of the Addon. | | `service.alert_creation` | string | | Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `service.alert_grouping_parameters` | one of: object \| object | | Alert Grouping Parameters. **Deprecated.** | | `service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `service.alert_grouping` | string | | Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `service.alert_grouping_timeout` | integer | | The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `service.auto_pause_notifications_parameters` | object | | Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | Example: Response Example ```json { "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 } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/get-service-custom-field-values # Get Custom Field Values `GET https://api.pagerduty.com/services/{id}/custom_fields/values` Get custom field values for a service. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The list of custom field values. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of object | | | | `custom_fields[].data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `custom_fields[].description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `custom_fields[].display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `custom_fields[].field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `custom_fields[].id` | string | | The ID of the resource. | | `custom_fields[].name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].type` | string | | Determines the type of the reference. One of: `field_value`. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | | | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Response Example ```json { "custom_fields": [ { "data_type": "string", "description": "environment where service instance runs", "display_name": "Runtime Environment", "field_type": "single_value_fixed", "id": "PT4KHEE", "name": "environment", "type": "field_value", "value": "production" } ] } ``` Example: Response Example ```json { "custom_fields": [ { "data_type": "string", "description": "environment where service instance runs", "display_name": "Runtime Environment", "field_type": "multi_value_fixed", "id": "PT4KHEE", "name": "environment", "type": "field_value", "value": [ "production", "staging" ] } ] } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/get-service-event-rule # Get an Event Rule from a Service `GET https://api.pagerduty.com/services/{id}/rules/{rule_id}` Get an Event Rule from a Service. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Event Rule object. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule on the Service. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching Event Rule is found or the end of the list is reached. | | `rule.actions` | object | | When an event matches this Event Rule, the actions that will be taken to change the resulting Alert and Incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | Example: Response Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "self": "https://api.pagerduty.com/services/PI2KBWI/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "class" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was modified by an Event Rule" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "custom_details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/get-service-integration # View an integration `GET https://api.pagerduty.com/services/{id}/integrations/{integration_id}` Get details about an integration belonging to a service. A service may represent an application, component, or team you wish to open incidents against. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `integration_id` | string | yes | The integration ID on the service. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `services`, `vendors`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The integration that was requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | | | `integration.id` | string | | Read-only. | | `integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.type` | string | | One of: `aws_cloudwatch_inbound_integration`, `cloudkick_inbound_integration`, `event_transformer_api_inbound_integration`, `generic_email_inbound_integration`, `generic_events_api_inbound_integration`, `keynote_inbound_integration`, `nagios_inbound_integration`, `pingdom_inbound_integration`, `sql_monitor_inbound_integration`, `events_api_v2_inbound_integration`. | | `integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.name` | string | | The name of this integration. | | `integration.service` | object | | | | `integration.service.id` | string | yes | Read-only. | | `integration.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.service.type` | string | yes | One of: `service_reference`. | | `integration.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.created_at` | string (date-time) | | The date/time when this integration was created. Read-only. | | `integration.vendor` | object | | | | `integration.vendor.id` | string | yes | Read-only. | | `integration.vendor.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.vendor.type` | string | yes | One of: `vendor_reference`. | | `integration.vendor.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.vendor.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.integration_email` | string | | Specify for generic_email_inbound_integration. Must be set to an email address @your-subdomain.pagerduty.com. | | `integration.email_incident_creation` | string | | Specify for generic_email_inbound_integration. One of: `on_new_email`, `on_new_email_subject`, `only_if_no_open_incidents`, `use_rules`. | | `integration.email_filter_mode` | string | | Specify for generic_email_inbound_integration. May override email_incident_creation. One of: `all-email`, `or-rules-email`, `and-rules-email`. | | `integration.email_parsers` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_parsers[].action` | string | yes | One of: `trigger`, `resolve`. | | `integration.email_parsers[].match_predicate` | object | yes | | | `integration.email_parsers[].match_predicate.type` | string | yes | One of: `all`, `any`, `not`, `contains`, `exactly`, `regex`. | | `integration.email_parsers[].match_predicate.matcher` | string | | Required if the type is `contains`, `exactly` or `regex`. Min length: 1. | | `integration.email_parsers[].match_predicate.part` | string | yes | The email field that will attempt to use the matcher expression. Required if the type is `contains`, `exactly` or `regex`. One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].match_predicate.children` | array of MatchPredicate (recursive) | yes | Additional matchers to be run. Must be not empty if the type is `all`, `any`, or `not`. | | `integration.email_parsers[].value_extractors` | array of object | | Additional values that will be pulled in to the Incident object. Exactly one value extractor must have a `value_name` of `incident_key`. Min items: 1. Items must be unique. | | `integration.email_parsers[].value_extractors[].type` | string | yes | One of: `entire`, `regex`, `between`. | | `integration.email_parsers[].value_extractors[].part` | string | yes | One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].value_extractors[].value_name` | string | yes | The field name to set in the Incident object. Exactly one must use the `value_name` of `incident_key` Min length: 1. | | `integration.email_parsers[].value_extractors[].regex` | string | | | | `integration.email_parsers[].value_extractors[].starts_after` | string | | | | `integration.email_parsers[].value_extractors[].ends_with` | string | | | | `integration.email_parsing_fallback` | string | | Specify for generic_email_inbound_integration. One of: `open_new_incident`, `discard`. | | `integration.email_filters` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_filters[].subject_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].subject_regex` | string | | Specify if subject_mode is set to match or no-match. | | `integration.email_filters[].body_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].body_regex` | string | | Specify if body_mode is set to match or no-match. | | `integration.email_filters[].from_email_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].from_email_regex` | string | | Specify if from_email_mode is set to match or no-match. | Example: Response Example ```json { "integration": { "id": "PE1U9CH", "type": "generic_email_inbound_integration", "summary": "Email", "self": "https://api.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "html_url": "https://subdomain.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "name": "Email", "service": { "id": "PQL78HM", "type": "service_reference", "summary": "My Email-Based Integration", "self": "https://api.pagerduty.com/services/PQL78HM", "html_url": "https://subdomain.pagerduty.com/service-directory/PQL78HM" }, "created_at": "2015-10-14T13:33:02-07:00", "vendor": { "id": "P8JX75F", "type": "vendor_reference", "summary": "Autotask", "self": "https://api.pagerduty.com/vendors/P8JX75F" }, "integration_email": "my-email-based-integration@subdomain.pagerduty.com" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/list-service-audit-records # List audit records for a service `GET https://api.pagerduty.com/services/{id}/audit/records` The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schedule. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PDRECORDID1_SERVICE_CREATED", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "111lDEOIH-534-4ljhLHJjh111", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference" } ], "method": { "type": "api_token", "truncated_token": "3usr" }, "root_resource": { "id": "PN2YA40", "type": "service_reference", "summary": "Documentation Hub" }, "action": "create", "details": { "resource": { "id": "PD_SERVICE_ID", "type": "service_reference", "summary": "Documentation Hub" }, "fields": [ { "name": "name", "value": "Documentation Hub" }, { "name": "description", "value": "Centralized documentation" }, { "name": "incident_severity", "value": "always_high" }, { "name": "alert_creation", "value": "create_alerts_and_incidents" }, { "name": "auto_resolve_timeout", "value": "" }, { "name": "acknowledgement_timeout", "value": "" }, { "name": "alert_grouping", "value": null }, { "name": "alert_grouping_timeout", "value": "" } ], "references": [ { "name": "escalation_policy", "added": [ { "id": "PD_SERVICE_ID", "summary": "Default", "type": "escalation_policy_reference" } ] } ] } } ], "next_cursor": null, "limit": 10 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/list-service-event-rules # List Service's Event Rules `GET https://api.pagerduty.com/services/{id}/rules` List Event Rules on a Service. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `migrated_metadata`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of Event Rule objects. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `migrated_at` | string (date-time) | | The date/time the service's Event Rules were converted to a Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `migrated_by` | object | | Reference to the user that converted the service's Event Rules to a Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `migrated_by.id` | string | | Read-only. | | `migrated_by.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `migrated_by.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `migrated_status` | string | | The status indicating whether the service's Event Rules were successfully converted to a Service Orchestration. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `completed`. | | `migrated_to` | object | | Reference to the Service Orchestration that the service's Event Rules were converted to. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. | | `migrated_to.id` | string | | Read-only. | | `migrated_to.type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `migrated_to.self` | string (url) | | The API show URL at which the object is accessible. Read-only. | | `migrated_via` | string | | Indicates whether the conversion was performed via the PagerDuty API or PagerDuty website. This property is only included if the `migrated_metadata` query parameter is provided. Read-only. One of: `API`, `UI`. | | `rules` | array of object | | The paginated list of Event Rules of the Service. | | `rules[].id` | string | | ID of the Event Rule. Read-only. | | `rules[].self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rules[].disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rules[].conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rules[].conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rules[].conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rules[].conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rules[].conditions.subconditions[].parameters` | object | yes | | | `rules[].conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rules[].conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rules[].conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rules[].time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rules[].time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rules[].time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rules[].time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rules[].time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rules[].time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rules[].time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rules[].time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rules[].time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rules[].variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rules[].variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rules[].variables[].name` | string | yes | The name of the variable. | | `rules[].variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rules[].variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rules[].variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rules[].position` | integer | | Position/index of the Event Rule on the Service. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching Event Rule is found or the end of the list is reached. | | `rules[].actions` | object | | When an event matches this Event Rule, the actions that will be taken to change the resulting Alert and Incident. | | `rules[].actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rules[].actions.annotate.value` | string | yes | The content of the note. | | `rules[].actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rules[].actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rules[].actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rules[].actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rules[].actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rules[].actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rules[].actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rules[].actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rules[].actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rules[].actions.priority.value` | string | yes | The priority ID. | | `rules[].actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rules[].actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rules[].actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rules[].actions.suppress.value` | boolean | yes | | | `rules[].actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rules[].actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rules[].actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rules[].actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rules[].actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | Example: Response Example ```json { "rules": [ { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "self": "https://api.pagerduty.com/service-directory/PI2KBWI/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "class" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "severity": { "value": "info" }, "extractions": [ { "target": "dedup_key", "template": "{{error_level}} error on host {{host}}" } ] }, "variables": [ { "name": "error_level", "type": "regex", "parameters": { "value": ".*error level is (\\w+)\\.", "path": "summary" } }, { "name": "host", "type": "regex", "parameters": { "value": "(.*)-USW2", "path": "source" } } ] } ], "limit": 25, "migrated_at": "2023-06-14T13:51:31Z", "migrated_by": { "id": "P8B9WR8", "self": "https://api.pagerduty.com/users/P8B9WR8", "type": "user_reference" }, "migrated_status": "completed", "migrated_to": { "id": "PI2KBWI", "self": "https://api.pagerduty.com/event_orchestrations/services/PI2KBWI", "type": "event_orchestration_reference" }, "migrated_via": "API", "offset": 0, "more": false, "total": null } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/list-service-feature-enablements # Get Enablements for a Service `GET https://api.pagerduty.com/services/{id}/enablements` List all feature enablement settings for a service. Currently, only the `aiops` enablement is supported. For any account with the AIOps product addon, every service will have AIOps features enabled by default. **Warning conditions**: - If the account is not entitled to use AIOps features, a warning will be returned alongside the enablement data. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The list of feature enablement settings for the service. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `enablements` | array of object | | Array of feature enablement settings. | | `enablements[].feature` | string | | The name of the product addon whose set of features will be enabled or disabled. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Read-only. | | `enablements[].enabled` | boolean | yes | A boolean value indicating whether the specified product addon is enabled or disabled. | | `enablements[].updated_at` | string (date-time) | | The time the feature enablement was last updated. Read-only. | | `enablements[].warnings` | array of object | | An array of warnings related to this feature enablement. Only present if warning conditions are met. Read-only. | | `enablements[].warnings[].message` | string | | The warning message. | Example: Success Response ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z" } ] } ``` Example: Response with No Entitlement Warning ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z", "warnings": [ { "message": "Your account is not entitled to use AIOps features for this Service." } ] } ] } ``` Example: Default Response (No Settings Configured) ```json { "enablements": [ { "feature": "aiops", "enabled": true, "updated_at": null } ] } ``` ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/list-services # List services `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `time_zone` | string (tzinfo) | | Time zone in which results will be rendered. This will default to the account time zone. | | `sort_by` | string | | Used to specify the field you wish to sort the results on. One of: `name`, `name:asc`, `name:desc`. Default: `name`. | | `include[]` | string | | Array of additional details to include. One of: `escalation_policies`, `teams`, `integrations`, `auto_pause_notifications_parameters`. Items must be unique. | | `name` | string | | Filters the results, showing only services with the specified name. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of services. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `services` | array of object | yes | | | `services[].id` | string | | Read-only. | | `services[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].type` | string | yes | The type of object being created. One of: `service`. Default: `service`. | | `services[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `services[].name` | string | | The name of the service. | | `services[].description` | string | | The user-provided description of the service. | | `services[].auto_resolve_timeout` | integer | | Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `services[].acknowledgement_timeout` | integer | | Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `services[].created_at` | string (date-time) | | The date/time when this service was created. Read-only. | | `services[].status` | string | | The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `services[].last_incident_timestamp` | string (date-time) | | The date/time when the most recent incident was created for this service. Read-only. | | `services[].escalation_policy` | object | yes | | | `services[].escalation_policy.id` | string | yes | Read-only. | | `services[].escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `services[].escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `services[].response_play` | | | Response plays associated with this service. **Deprecated.** | | `services[].teams` | array of object | | The set of teams associated with this service. Read-only. | | `services[].teams[].id` | string | yes | Read-only. | | `services[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].teams[].type` | string | yes | One of: `team_reference`. | | `services[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `services[].integrations` | array of object | | An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `services[].integrations[].id` | string | yes | Read-only. | | `services[].integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `services[].integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `services[].incident_urgency_rule` | object | | | | `services[].incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `services[].incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `services[].incident_urgency_rule.during_support_hours` | object | | | | `services[].incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `services[].incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `services[].incident_urgency_rule.outside_support_hours` | object | | Same fields as `services[].incident_urgency_rule.during_support_hours` above. | | `services[].support_hours` | object | | | | `services[].support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `services[].support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `services[].support_hours.days_of_week` | array of integer | | Read-only. | | `services[].support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `services[].support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `services[].scheduled_actions` | array of object | | An array containing scheduled actions for the service. | | `services[].scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `services[].scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `services[].scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `services[].scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `services[].scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `services[].addons` | array of object | | The array of Add-ons associated with this service. Read-only. | | `services[].addons[].id` | string | yes | Read-only. | | `services[].addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `services[].addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `services[].addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `services[].addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `services[].addons[].src` | string (url) | | The URL source of the Addon. | | `services[].addons[].name` | string | | The user entered name of the Addon. | | `services[].alert_creation` | string | | Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `services[].alert_grouping_parameters` | one of: object \| object | | Alert Grouping Parameters. **Deprecated.** | | `services[].alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `services[].alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `services[].alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `services[].alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `services[].alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `services[].alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `services[].alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `services[].alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `services[].alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `services[].alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `services[].alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `services[].alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `services[].alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `services[].alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `services[].alert_grouping` | string | | Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `services[].alert_grouping_timeout` | integer | | The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `services[].auto_pause_notifications_parameters` | object | | Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `services[].auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `services[].auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `services[].auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/update-service # Update a service `PUT https://api.pagerduty.com/services/{id}` Update an existing service. A service may represent an application, component, or team you wish to open incidents against. There is a limit of 100,000 open Incidents per Service. If the limit is reached and you disable `auto_resolve_timeout` (set to 0 or null), the API will respond with an error. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The service to be updated. | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | | | `service.id` | string | | Read-only. | | `service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.type` | string | yes | The type of object being created. One of: `service`. Default: `service`. | | `service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.name` | string | | The name of the service. | | `service.description` | string | | The user-provided description of the service. | | `service.auto_resolve_timeout` | integer | | Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. | | `service.acknowledgement_timeout` | integer | | Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. | | `service.created_at` | string (date-time) | | The date/time when this service was created. Read-only. | | `service.status` | string | | The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. | | `service.last_incident_timestamp` | string (date-time) | | The date/time when the most recent incident was created for this service. Read-only. | | `service.escalation_policy` | object | yes | | | `service.escalation_policy.id` | string | yes | Read-only. | | `service.escalation_policy.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. | | `service.escalation_policy.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.escalation_policy.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.response_play` | | | Response plays associated with this service. **Deprecated.** | | `service.teams` | array of object | | The set of teams associated with this service. Read-only. | | `service.teams[].id` | string | yes | Read-only. | | `service.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.teams[].type` | string | yes | One of: `team_reference`. | | `service.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.integrations` | array of object | | An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. | | `service.integrations[].id` | string | yes | Read-only. | | `service.integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. | | `service.integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.incident_urgency_rule` | object | | | | `service.incident_urgency_rule.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.during_support_hours` | object | | | | `service.incident_urgency_rule.during_support_hours.type` | string | | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. | | `service.incident_urgency_rule.during_support_hours.urgency` | string | | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. | | `service.incident_urgency_rule.outside_support_hours` | object | | Same fields as `service.incident_urgency_rule.during_support_hours` above. | | `service.support_hours` | object | | | | `service.support_hours.type` | string | | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. | | `service.support_hours.time_zone` | string (activesupport-time-zone) | | The time zone for the support hours. | | `service.support_hours.days_of_week` | array of integer | | Read-only. | | `service.support_hours.start_time` | string (time) | | The support hours' starting time of day (date portion is ignored) | | `service.support_hours.end_time` | string (time) | | The support hours' ending time of day (date portion is ignored) | | `service.scheduled_actions` | array of object | | An array containing scheduled actions for the service. | | `service.scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. | | `service.scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. | | `service.scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. | | `service.scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. | | `service.scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. | | `service.addons` | array of object | | The array of Add-ons associated with this service. Read-only. | | `service.addons[].id` | string | yes | Read-only. | | `service.addons[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `service.addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. | | `service.addons[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `service.addons[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `service.addons[].src` | string (url) | | The URL source of the Addon. | | `service.addons[].name` | string | | The user entered name of the Addon. | | `service.alert_creation` | string | | Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. | | `service.alert_grouping_parameters` | one of: object \| object | | Alert Grouping Parameters. **Deprecated.** | | `service.alert_grouping_parameters.type` | string \| null | | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. | | `service.alert_grouping_parameters.config` | one of: object \| object \| object | | (Alert Grouping Parameters) | | `service.alert_grouping_parameters.config.time_window` | integer | | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.config.timeout` | integer | | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. | | `service.alert_grouping_parameters.config.aggregate` | string | | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. | | `service.alert_grouping_parameters.config.fields` | array of string | | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. | | `service.alert_grouping_parameters.config.time_window` | integer | | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. | | `service.alert_grouping_parameters.config.recommended_time_window` | integer | | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. | | `service.alert_grouping_parameters.id` | string | | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. | | `service.alert_grouping_parameters.type` | string | | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. | | `service.alert_grouping_parameters.summary` | string | | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. | | `service.alert_grouping_parameters.self` | string | | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. | | `service.alert_grouping_parameters.html_url` | string | | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. | | `service.alert_grouping` | string | | Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. | | `service.alert_grouping_timeout` | integer | | The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** | | `service.auto_pause_notifications_parameters` | object | | Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. | | `service.auto_pause_notifications_parameters.enabled` | boolean | | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. | | `service.auto_pause_notifications_parameters.timeout` | integer | | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. | | `service.auto_pause_notifications_parameters.recommended_timeout` | integer | | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. | Example: Request Example ```json { "service": { "type": "service", "name": "My Web App", "description": "My cool web application that does things.", "auto_resolve_timeout": 14400, "acknowledgement_timeout": 600, "status": "active", "escalation_policy": { "id": "PWIP6CQ", "type": "escalation_policy_reference" }, "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" } ], "alert_creation": "create_alerts_and_incidents", "alert_grouping_parameters": { "type": "time", "config": { "timeout": 2 } }, "auto_pause_notifications_parameters": { "enabled": true, "timeout": 300 } } } ``` ## Response 200 The service that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | yes | Same fields as `service` above. | Example: Response Example ```json { "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", "alert_grouping_parameters": { "type": "time", "config": { "timeout": 2 } }, "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 } } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/update-service-custom-field-values # Update Custom Field Values `PUT https://api.pagerduty.com/services/{id}/custom_fields/values` Set custom field values for a service. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of one of: object \| object | yes | | | `custom_fields[].id` | string | yes | (Value by Field ID) The ID of the resource. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | yes | (Value by Field ID) | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | | `custom_fields[].name` | string | yes | (Value by Field Name) The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | yes | (Value by Field Name) | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Request Example ```json { "custom_fields": [ { "id": "PT4KHEE", "value": "production" } ] } ``` Example: Request Example ```json { "custom_fields": [ { "name": "environment", "value": "production" } ] } ``` Example: Request Example ```json { "custom_fields": [ { "id": "PT4KHEE", "value": [ "production", "staging" ] } ] } ``` ## Response 201 The custom field values were updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `custom_fields` | array of object | yes | | | `custom_fields[].data_type` | string | | The kind of data the custom field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `custom_fields[].description` | string \| null | | A description of the data this field contains. Max length: 1000. | | `custom_fields[].display_name` | string | | The human-readable name of the field. This must be unique across an account. Max length: 50. | | `custom_fields[].field_type` | string | | The type of data this field contains. In combination with the `data_type` field. One of: `single_value`, `single_value_fixed`, `multi_value`, `multi_value_fixed`. | | `custom_fields[].id` | string | | The ID of the resource. | | `custom_fields[].name` | string | | The name of the field. May include ASCII characters, specifically lowercase letters, digits, and underescores. The `name` for a Field must be unique and cannot be changed once created. Max length: 50. | | `custom_fields[].type` | string | | Determines the type of the reference. One of: `field_value`. | | `custom_fields[].value` | one of: object \| object \| object \| object \| object \| object | | | | `custom_fields[].value.value` | boolean \| null | | (Boolean) | | `custom_fields[].value.value` | number \| null | | (Float) | | `custom_fields[].value.value` | integer \| null | | (Integer) | | `custom_fields[].value.value` | one of: string \| null \| array \| null | | (String) | | `custom_fields[].value.value` | string \| null (date-time) | | (Datetime) | | `custom_fields[].value.value` | string \| null (uri) | | (Url) Max length: 200. | Example: Response Example ```json { "custom_fields": [ { "data_type": "string", "description": "environment where service instance runs", "display_name": "Runtime Environment", "field_type": "single_value_fixed", "id": "PT4KHEE", "name": "environment", "type": "field_value", "value": "production" } ] } ``` Example: Response Example ```json { "custom_fields": [ { "data_type": "string", "description": "environment where service instance runs", "display_name": "Runtime Environment", "field_type": "multi_value_fixed", "id": "PT4KHEE", "name": "environment", "type": "field_value", "value": [ "production", "staging" ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/update-service-event-rule # Update an Event Rule on a Service `PUT https://api.pagerduty.com/services/{id}/rules/{rule_id}` Update an Event Rule on a Service. Note that the endpoint supports partial updates, so any number of the writable fields can be provided. > ### End-of-life > Rulesets and Event Rules will end-of-life soon. We highly recommend that you [migrate to Event Orchestration](https://support.pagerduty.com/docs/migrate-to-event-orchestration) as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `rule_id` | string | yes | The id of the Event Rule to retrieve. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | | | `rule.id` | string | | ID of the Event Rule. Read-only. | | `rule.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | | `rule.disabled` | boolean | | Indicates whether the Event Rule is disabled and would therefore not be evaluated. | | `rule.conditions` | object | | Conditions evaluated to check if an event matches this Event Rule. Is always empty for the catch_all rule, though. | | `rule.conditions.operator` | string | yes | Operator to combine sub-conditions. One of: `and`, `or`. | | `rule.conditions.subconditions` | array of object | yes | Array of sub-conditions. | | `rule.conditions.subconditions[].operator` | string | yes | The type of operator to apply. One of: `exists`, `nexists`, `equals`, `nequals`, `contains`, `ncontains`, `matches`, `nmatches`. | | `rule.conditions.subconditions[].parameters` | object | yes | | | `rule.conditions.subconditions[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a serivce, this will have to be a PD-CEF field. | | `rule.conditions.subconditions[].parameters.value` | string | yes | Value to apply to the operator. | | `rule.conditions.subconditions[].parameters.options` | object | | Options to configure the operator. | | `rule.time_frame` | object | | Time-based conditions for limiting when the rule is active. | | `rule.time_frame.active_between` | object | | A fixed window of time during which the rule is active. | | `rule.time_frame.active_between.start_time` | integer | yes | The start time in milliseconds. | | `rule.time_frame.active_between.end_time` | integer | yes | End time in milliseconds. | | `rule.time_frame.scheduled_weekly` | object | | A reccuring window of time based on the day of the week, during which the rule is active. | | `rule.time_frame.scheduled_weekly.start_time` | integer | yes | The amount of milliseconds into the day at which the window starts. | | `rule.time_frame.scheduled_weekly.duration` | integer | yes | The duration of the window in milliseconds. | | `rule.time_frame.scheduled_weekly.timezone` | string | yes | The timezone. | | `rule.time_frame.scheduled_weekly.weekdays` | array of integer | yes | An array of day values. Ex [1, 3, 5] is Monday, Wednesday, Friday. | | `rule.variables` | array of object | | [Early Access] Populate variables from event payloads and use those variables in other event actions. | | `rule.variables[].type` | string | yes | The type of operation to populate the variable. One of: `regex`. | | `rule.variables[].name` | string | yes | The name of the variable. | | `rule.variables[].parameters` | object | yes | The parameters for performing the operation to populate the. | | `rule.variables[].parameters.value` | string | yes | The value for the operation. For example, an RE2 regular expression for regex-type variables. | | `rule.variables[].parameters.path` | string | yes | Path to a field in an event, in dot-notation. For Event Rules on a Service, this will have to be a PD-CEF field. | | `rule.position` | integer | | Position/index of the Event Rule on the Service. Starting from position 0 (the first rule), rules are evaluated one-by-one until a matching Event Rule is found or the end of the list is reached. | | `rule.actions` | object | | When an event matches this Event Rule, the actions that will be taken to change the resulting Alert and Incident. | | `rule.actions.annotate` | object \| null | | Set a note on the resulting incident. | | `rule.actions.annotate.value` | string | yes | The content of the note. | | `rule.actions.event_action` | object \| null | | Set whether the resulting alert status is trigger or resolve. | | `rule.actions.event_action.value` | string | yes | One of: `trigger`, `resolve`. | | `rule.actions.extractions` | array of one of: object \| object | | Dynamically extract values to set and modify new and existing PD-CEF fields. | | `rule.actions.extractions[].target` | string | yes | (option 1) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].source` | string | yes | (option 1) The path to the event field where the regex will be applied to extract a value. | | `rule.actions.extractions[].regex` | string | yes | (option 1) A RE2 regular expression. If it contains one or more capture groups, their values will be extracted and appended together. If it contains no capture groups, the whole match is used. | | `rule.actions.extractions[].target` | string | yes | (option 2) The PD-CEF field that will be set with the value from the regex. | | `rule.actions.extractions[].template` | string | yes | (option 2) A value that will be used to populate the target PD-CEF field. You can include variables extracted from the payload by using string interpolation. | | `rule.actions.priority` | object \| null | | Set the priority ID for the resulting incident. You can find the priority you want by calling the priorities endpoint. | | `rule.actions.priority.value` | string | yes | The priority ID. | | `rule.actions.severity` | object \| null | | Set the severity of the resulting alert. | | `rule.actions.severity.value` | string | yes | One of: `info`, `warning`, `error`, `critical`. | | `rule.actions.suppress` | object | | Set whether the resulting alert is suppressed. Can optionally be used with a threshold where resulting alerts will be suppressed until the threshold is met in a window of time. If using a threshold the rule must also set a route action. | | `rule.actions.suppress.value` | boolean | yes | | | `rule.actions.suppress.threshold_value` | integer | | The number of occurences needed during the window of time to trigger the theshold. | | `rule.actions.suppress.threshold_time_unit` | string | | The time unit for the window of time. One of: `seconds`, `minutes`, `hours`. | | `rule.actions.suppress.threshold_time_amount` | integer | | The amount of time units for the window of time. | | `rule.actions.suspend` | object \| null | | Set the length of time to suspend the resulting alert before triggering. Rules with a suspend action must also set a route action, and cannot have a suppress with threshold action. | | `rule.actions.suspend.value` | integer | yes | The amount of time to suspend the alert in seconds. | | `rule_id` | string | yes | The id of the Event Rule to update on the Service. | Example: Example: Enable suppress action ```json { "rule_id": "7123bdd1-74e8-4aa7-aa38-4a9ebe123456", "rule": { "actions": { "suppress": { "value": true } } } } ``` Example: Example: Disable rule ```json { "rule_id": "7123bdd1-74e8-4aa7-aa38-4a9ebe123456", "rule": { "disabled": true } } ``` ## Response 200 The Event Rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `rule` | object | | Same fields as `rule` above. | Example: Response Example ```json { "rule": { "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "position": 0, "disabled": false, "self": "https://api.pagerduty.com/services/PI2KBWI/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b", "conditions": { "operator": "and", "subconditions": [ { "operator": "contains", "parameters": { "value": "mysql", "path": "class" } } ] }, "time_frame": { "active_between": { "start_time": 1577880000000, "end_time": 1580558400000 } }, "actions": { "annotate": { "value": "This incident was modified by an Event Rule" }, "priority": { "value": "PCMUB6F" }, "severity": { "value": "warning" }, "extractions": [ { "target": "dedup_key", "source": "custom_details.error_summary", "regex": "Host (.*) is experiencing errors" } ] } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 405 The request was received and recognized by the server, but its HTTP method was rejected for the requested resource. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 409 The request conflicts with the current state of the server. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/update-service-feature-enablement # Update an Enablement for a Service `PUT https://api.pagerduty.com/services/{id}/enablements/{feature_name}` Update the feature enablement setting for a specific product addon on a service. This setting controls enabling or disabling the set of features contained within the addon. Currently, only `aiops` is supported as a valid feature enablement. **Warning conditions**: - If the account is not entitled to use AIOps features, the setting will be updated, but a warning will be returned. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `feature_name` | string | yes | The feature enablement identifier, typically the name of the product addon. Currently only `aiops` is supported. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. One of: `aiops`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The feature enablement setting to apply. | Field | Type | Required | Description | |---|---|---|---| | `enablement` | object | yes | | | `enablement.feature` | string | | The name of the product addon whose set of features will be enabled or disabled. For PDRP customers, this feature is branded **Signal Intelligence** in the PagerDuty product UI. The API field names and values (e.g. `aiops`) are unchanged. Read-only. | | `enablement.enabled` | boolean | yes | A boolean value indicating whether the specified product addon is enabled or disabled. | | `enablement.updated_at` | string (date-time) | | The time the feature enablement was last updated. Read-only. | | `enablement.warnings` | array of object | | An array of warnings related to this feature enablement. Only present if warning conditions are met. Read-only. | | `enablement.warnings[].message` | string | | The warning message. | Example: Enable AIOps ```json { "enablement": { "enabled": true } } ``` Example: Disable AIOps ```json { "enablement": { "enabled": false } } ``` ## Response 200 The feature enablement setting was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `enablement` | object | | Same fields as `enablement` above. | Example: Success Response ```json { "enablement": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z" } ] } ``` Example: Response with No Entitlement Warning ```json { "enablement": [ { "feature": "aiops", "enabled": true, "updated_at": "2025-04-25T15:00:00Z", "warnings": [ { "message": "Your account is not entitled to use AIOps features for this Service." } ] } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/services/update-service-integration # Update an existing integration `PUT https://api.pagerduty.com/services/{id}/integrations/{integration_id}` Update an integration belonging to a Service. A service may represent an application, component, or team you wish to open incidents against. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#services) Scoped OAuth requires: `services.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `integration_id` | string | yes | The integration ID on the service. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The integration to be updated | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | | | `integration.id` | string | | Read-only. | | `integration.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.type` | string | | One of: `aws_cloudwatch_inbound_integration`, `cloudkick_inbound_integration`, `event_transformer_api_inbound_integration`, `generic_email_inbound_integration`, `generic_events_api_inbound_integration`, `keynote_inbound_integration`, `nagios_inbound_integration`, `pingdom_inbound_integration`, `sql_monitor_inbound_integration`, `events_api_v2_inbound_integration`. | | `integration.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.name` | string | | The name of this integration. | | `integration.service` | object | | | | `integration.service.id` | string | yes | Read-only. | | `integration.service.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.service.type` | string | yes | One of: `service_reference`. | | `integration.service.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.service.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.created_at` | string (date-time) | | The date/time when this integration was created. Read-only. | | `integration.vendor` | object | | | | `integration.vendor.id` | string | yes | Read-only. | | `integration.vendor.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integration.vendor.type` | string | yes | One of: `vendor_reference`. | | `integration.vendor.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integration.vendor.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration.integration_email` | string | | Specify for generic_email_inbound_integration. Must be set to an email address @your-subdomain.pagerduty.com. | | `integration.email_incident_creation` | string | | Specify for generic_email_inbound_integration. One of: `on_new_email`, `on_new_email_subject`, `only_if_no_open_incidents`, `use_rules`. | | `integration.email_filter_mode` | string | | Specify for generic_email_inbound_integration. May override email_incident_creation. One of: `all-email`, `or-rules-email`, `and-rules-email`. | | `integration.email_parsers` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_parsers[].action` | string | yes | One of: `trigger`, `resolve`. | | `integration.email_parsers[].match_predicate` | object | yes | | | `integration.email_parsers[].match_predicate.type` | string | yes | One of: `all`, `any`, `not`, `contains`, `exactly`, `regex`. | | `integration.email_parsers[].match_predicate.matcher` | string | | Required if the type is `contains`, `exactly` or `regex`. Min length: 1. | | `integration.email_parsers[].match_predicate.part` | string | yes | The email field that will attempt to use the matcher expression. Required if the type is `contains`, `exactly` or `regex`. One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].match_predicate.children` | array of MatchPredicate (recursive) | yes | Additional matchers to be run. Must be not empty if the type is `all`, `any`, or `not`. | | `integration.email_parsers[].value_extractors` | array of object | | Additional values that will be pulled in to the Incident object. Exactly one value extractor must have a `value_name` of `incident_key`. Min items: 1. Items must be unique. | | `integration.email_parsers[].value_extractors[].type` | string | yes | One of: `entire`, `regex`, `between`. | | `integration.email_parsers[].value_extractors[].part` | string | yes | One of: `body`, `subject`, `from_addresses`. | | `integration.email_parsers[].value_extractors[].value_name` | string | yes | The field name to set in the Incident object. Exactly one must use the `value_name` of `incident_key` Min length: 1. | | `integration.email_parsers[].value_extractors[].regex` | string | | | | `integration.email_parsers[].value_extractors[].starts_after` | string | | | | `integration.email_parsers[].value_extractors[].ends_with` | string | | | | `integration.email_parsing_fallback` | string | | Specify for generic_email_inbound_integration. One of: `open_new_incident`, `discard`. | | `integration.email_filters` | array of object | | Specify for generic_email_inbound_integration. Min items: 1. Items must be unique. | | `integration.email_filters[].subject_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].subject_regex` | string | | Specify if subject_mode is set to match or no-match. | | `integration.email_filters[].body_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].body_regex` | string | | Specify if body_mode is set to match or no-match. | | `integration.email_filters[].from_email_mode` | string | yes | One of: `match`, `no-match`, `always`. | | `integration.email_filters[].from_email_regex` | string | | Specify if from_email_mode is set to match or no-match. | Example: Request Example ```json { "integration": { "type": "generic_email_inbound_integration", "name": "Email", "service": { "id": "PQL78HM", "type": "service_reference", "summary": "My Email-Based Integration", "self": "https://api.pagerduty.com/services/PQL78HM", "html_url": "https://subdomain.pagerduty.com/service-directory/PQL78HM" }, "integration_email": "my-email-based-integration@subdomain.pagerduty.com", "vendor": { "type": "vendor_reference", "id": "PZD94QK" } } } ``` ## Response 200 The integration that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `integration` | object | yes | Same fields as `integration` above. | Example: Response Example ```json { "integration": { "id": "PE1U9CH", "type": "generic_email_inbound_integration", "summary": "Email", "self": "https://api.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "html_url": "https://subdomain.pagerduty.com/services/PQL78HM/integrations/PE1U9CH", "name": "Email", "service": { "id": "PQL78HM", "type": "service_reference", "summary": "My Email-Based Integration", "self": "https://api.pagerduty.com/services/PQL78HM", "html_url": "https://subdomain.pagerduty.com/service-directory/PQL78HM" }, "created_at": "2015-10-14T13:33:02-07:00", "integration_email": "my-email-based-integration@subdomain.pagerduty.com" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/session-configurations/delete-session-configurations # Delete an account's session configurations. `DELETE https://api.pagerduty.com/session_configurations` Deletes the session configurations for a PagerDuty account that was previously set. The type parameter is required and specifies which configurations to delete. A single type ('mobile' or 'web') or comma-separated list may be passed in. Scoped OAuth requires: `session_configurations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `type` | string | yes | Session configuration type. This can be either 'mobile' or 'web', or a comma-separated list of both. One of: `mobile`, `web`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 Session Configurations deleted successfully ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/session-configurations/get-session-configurations # Get an account's session configurations `GET https://api.pagerduty.com/session_configurations` Retrieves session configurations for a PagerDuty account. Returns an array containing the requested configurations. If a specific type is requested, the array contains one item. If no type is specified, the array contains all available configurations (mobile and web). If no configurations exist, a 404 Not Found error will be returned. A Session Configuration needs to be created before it can be retrieved and used. Scoped OAuth requires: `session_configurations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `type` | string | | Session configuration type. If omitted, returns both mobile and web configurations. One of: `mobile`, `web`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Session Configurations retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `session_configurations` | array of object | yes | | | `session_configurations[].type` | string | yes | The session configuration type (mobile or web) One of: `mobile`, `web`. | | `session_configurations[].absolute_session_ttl` | integer | yes | Absolute session time to live in seconds. Minimum: 600. Maximum: 18144000. | | `session_configurations[].idle_session_ttl` | integer | yes | Idle session time to live in seconds. Minimum: 60. Maximum: 86400. | Example: Session Configurations Example ```json { "session_configurations": [ { "type": "web", "absolute_session_ttl": 3600, "idle_session_ttl": 600 }, { "type": "mobile", "absolute_session_ttl": 7200, "idle_session_ttl": 1200 } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/session-configurations/update-session-configurations # Configure an account's session configurations `PUT https://api.pagerduty.com/session_configurations` Creates or updates session configurations for a PagerDuty Account. The configurations will take effect immediately for new sessions, while existing sessions for the specified `types` are immediately revoked. Scoped OAuth requires: `session_configurations.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `type` | string | yes | Session configuration type. This can be either 'mobile' or 'web', or a comma-separated list of both. One of: `mobile`, `web`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `session_configuration` | object | yes | | | `session_configuration.absolute_session_ttl` | integer | yes | Absolute session time to live in seconds. Minimum: 600. Maximum: 18144000. | | `session_configuration.idle_session_ttl` | integer | yes | Idle session time to live in seconds. Minimum: 60. Maximum: 15552000. | ## Response 200 Session Configurations updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `session_configurations` | array of object | yes | | | `session_configurations[].type` | string | yes | The session configuration type (mobile or web) One of: `mobile`, `web`. | | `session_configurations[].absolute_session_ttl` | integer | yes | Absolute session time to live in seconds. Minimum: 600. Maximum: 18144000. | | `session_configurations[].idle_session_ttl` | integer | yes | Idle session time to live in seconds. Minimum: 60. Maximum: 86400. | Example: Put Session Configurations Example ```json { "session_configurations": [ { "type": "web", "absolute_session_ttl": 3600, "idle_session_ttl": 600 }, { "type": "mobile", "absolute_session_ttl": 7200, "idle_session_ttl": 1200 } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/sre-agent/delete-sre-memory # Delete an SRE Agent memory `DELETE https://api.pagerduty.com/sre_agent/memories/{id}` Permanently delete an SRE Agent memory. Deleting a runbook may not delete it immediately from a currently running conversation, but will remove it from all future conversations. To modify an in progress conversation ask the agent to delete the runbook instead. Scoped OAuth requires: `sre_agent.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The SRE Agent memory was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/sre-agent/list-sre-memories # List SRE Agent memories `GET https://api.pagerduty.com/sre_agent/memories` Search SRE Agent memories for the account. Memories are knowledge learned by the SRE Agent, including service runbooks, service profiles, incident playbooks, and incident summaries. Filter by service ID, incident ID, or memory type to retrieve relevant memories. Scoped OAuth requires: `incident.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results to return per page. Default: `20 - incident_summary`. Minimum: 1. Maximum: 100. | | `service_id` | string | | Filter memories by service ID. | | `incident_id` | string | | Filter memories by incident ID. | | `type` | string | | Filter memories by type. One of: `runbook`, `service_profile`, `incident_playbook`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of SRE Agent memories. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `memories` | array of object | yes | | | `memories[].id` | string | | The unique identifier for this memory. Read-only. | | `memories[].content` | string | yes | The content of the SRE memory. | | `memories[].attributes` | object | | Additional attributes associated with this memory. | | `memories[].attributes.account_id` | string | | The ID of the account this memory is associated with. | | `memories[].attributes.service_id` | string | | The ID of the service this memory is associated with. | | `memories[].attributes.incident_id` | string | | The ID of the incident this memory is associated with. | | `memories[].attributes.type` | string | | The type of memory. One of: `runbook`, `service_profile`, `incident_playbook`, `incident_summary`. | | `memories[].created_at` | string (date-time) | | The date and time the memory was created. Read-only. | | `memories[].updated_at` | string (date-time) | | The date and time the memory was last updated. Read-only. | Example: Response Example ```json { "memories": [ { "attributes": { "account_id": "PLHJ8WE", "service_id": "PJYY37U", "type": "service_profile" }, "content": "The Payment Processing Service handles all transaction processing with a 99.9% SLA target. Primary dependencies include Redis cache and PostgreSQL database.", "created_at": "2026-02-23T19:53:19.268Z", "id": "PLHJ8WE", "updated_at": "2026-02-23T19:53:19.268Z" }, { "attributes": { "account_id": "PLHJ8WE", "service_id": "PJYY37U", "type": "runbook" }, "content": "To restart the Payment Processing Service, first drain traffic from the load balancer, then run 'systemctl restart payment-service', and verify health checks pass before restoring traffic.", "created_at": "2026-02-24T17:15:42.123Z", "id": "PM4QR2T", "updated_at": "2026-02-24T17:15:42.123Z" }, { "attributes": { "account_id": "PLHJ8WE", "incident_id": "PX9LMN2", "service_id": "PJYY37U", "type": "incident_playbook" }, "content": "For payment timeout incidents, check Redis cache connection pool first, then verify database query performance. Restart cache service if connection pool is exhausted.", "created_at": "2026-02-25T22:22:10.543Z", "id": "PQRS123", "updated_at": "2026-02-25T22:22:10.543Z" }, { "attributes": { "account_id": "PLHJ8WE", "incident_id": "PX9LMN2", "service_id": "PJYY37U", "type": "incident_summary" }, "content": "Payment service experienced timeout errors due to exhausted Redis connection pool. Resolved by restarting cache service and increasing pool size from 50 to 100 connections.", "created_at": "2026-02-26T00:45:30.123Z", "id": "PXYZ789", "updated_at": "2026-02-26T00:45:30.123Z" } ], "limit": 20 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/sre-agent/update-sre-memory # Update an SRE Agent memory `PUT https://api.pagerduty.com/sre_agent/memories/{id}` Update an existing SRE Agent memory. Changes to the runbook may not update in a currently ongoing conversation, but will be available to new conversations. To modify the runbook for an in progress conversation update the runbook via the agent instead. Scoped OAuth requires: `sre_agent.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The SRE Agent memory to be updated. | Field | Type | Required | Description | |---|---|---|---| | `memory` | object | yes | | | `memory.content` | string | yes | The content of the SRE memory. | Example: Request Example ```json { "memory": { "content": "Updated memory content - The database connection pool was increased to 100 connections to resolve performance issues during peak load." } } ``` ## Response 200 The SRE Agent memory that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `memory` | object | yes | | | `memory.id` | string | | The unique identifier for this memory. Read-only. | | `memory.content` | string | yes | The content of the SRE memory. | | `memory.attributes` | object | | Additional attributes associated with this memory. | | `memory.attributes.account_id` | string | | The ID of the account this memory is associated with. | | `memory.attributes.service_id` | string | | The ID of the service this memory is associated with. | | `memory.attributes.incident_id` | string | | The ID of the incident this memory is associated with. | | `memory.attributes.type` | string | | The type of memory. One of: `runbook`, `service_profile`, `incident_playbook`, `incident_summary`. | | `memory.created_at` | string (date-time) | | The date and time the memory was created. Read-only. | | `memory.updated_at` | string (date-time) | | The date and time the memory was last updated. Read-only. | Example: Response Example ```json { "memory": { "attributes": { "account_id": "PLHJ8WE", "service_id": "PJYY37U", "type": "service_runbook" }, "content": "Updated memory content - The database connection pool was increased to 100 connections to resolve performance issues during peak load.", "created_at": "2026-02-23T19:53:19.268Z", "id": "PLHJ8WE", "type": "sre_memory", "updated_at": "2026-02-25T22:22:10.543Z" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/standards/list-resource-standards # List a resource's standards scores `GET https://api.pagerduty.com/standards/scores/{resource_type}/{id}` List standards applied to a specific resource Scoped OAuth requires: `standards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | Id of the resource to apply the standards. | | `resource_type` | string | yes | One of: `technical_services`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `resource_id` | string | | | | `resource_type` | string | | One of: `technical_service`. | | `score` | object | | | | `score.passing` | integer | | | | `score.total` | integer | | | | `standards` | array of object | | | | `standards[].active` | boolean | | | | `standards[].description` | string | | | | `standards[].id` | string | | | | `standards[].name` | string | | | | `standards[].type` | string | | | | `standards[].pass` | boolean | | | Example: Response Example ```json { "resource_id": "P0CPWBO", "resource_type": "technical_service", "score": { "passing": 1, "total": 1 }, "standards": [ { "active": true, "description": "A description provides critical context about what a service represents or is used for to inform team members and responders. The description should be kept concise and understandable by those without deep knowledge of the service.", "id": "01CXX38Q0U8XKHO4LNKXUJTBFG", "pass": true, "name": "Service has a description", "type": "has_technical_service_description" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/standards/list-resource-standards-many-services # List resources' standards scores `GET https://api.pagerduty.com/standards/scores/{resource_type}` List standards applied to a set of resources Scoped OAuth requires: `standards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `resource_type` | string | yes | One of: `technical_services`. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `ids` | array of string | yes | Ids of resources to apply the standards. Maximum of 100 items. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `resources` | array of object | | | | `resources[].resource_id` | string | | | | `resources[].resource_type` | string | | One of: `technical_service`. | | `resources[].score` | object | | | | `resources[].score.passing` | integer | | | | `resources[].score.total` | integer | | | | `resources[].standards` | array of object | | | | `resources[].standards[].active` | boolean | | | | `resources[].standards[].description` | string | | | | `resources[].standards[].id` | string | | | | `resources[].standards[].name` | string | | | | `resources[].standards[].type` | string | | | | `resources[].standards[].pass` | boolean | | | Example: Response Example ```json { "resources": [ { "resource_id": "P0CPWBO", "resource_type": "technical_service", "score": { "passing": 1, "total": 1 }, "standards": [ { "active": true, "description": "A description provides critical context about what a service represents or is used for to inform team members and responders. The description should be kept concise and understandable by those without deep knowledge of the service.", "id": "01CXX38Q0U8XKHO4LNKXUJTBFG", "pass": true, "name": "Service has a description", "type": "has_technical_service_description" } ] } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/standards/list-standards # List Standards `GET https://api.pagerduty.com/standards` Get all standards of an account. Scoped OAuth requires: `standards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `active` | boolean | | | | `resource_type` | string | | One of: `technical_service`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `standards` | array of object | | | | `standards[].active` | boolean | | | | `standards[].description` | string | | | | `standards[].id` | string | | | | `standards[].name` | string | | | | `standards[].type` | string | | | | `standards[].resource_type` | string | | One of: `technical_service`. | | `standards[].exclusions` | array of object | | | | `standards[].exclusions[].type` | string | | One of: `technical_service_reference`. | | `standards[].exclusions[].id` | string | | | | `standards[].inclusions` | array of object | | | | `standards[].inclusions[].type` | string | | One of: `technical_service_reference`. | | `standards[].inclusions[].id` | string | | | Example: Response Example ```json { "standards": [ { "active": true, "description": "A description provides critical context about what a service represents or is used for to inform team members and responders. The description should be kept concise and understandable by those without deep knowledge of the service.", "exclusions": [], "id": "01CXX38Q0U8XKHO4LNKXUJTBFG", "inclusions": [ { "type": "technical_service_reference", "id": "P0CPWBO" } ], "name": "Service has a description", "resource_type": "technical_service", "type": "has_technical_service_description" }, { "active": true, "description": "Ensure that no incident goes unaddressed, even if the on-call responder on the first level of the escalation policy is unavailable.", "exclusions": [], "id": "01CXX38Q0Y8D9IYFAEDCH5F53L", "inclusions": [], "name": "Service has an escalation policy with 2 or more unique levels", "resource_type": "technical_service", "type": "minimum_escalation_policy_rule_depth" }, { "active": true, "description": "Extensions or add-ons streamline incident response and communication processes by connecting PagerDuty services to other tools that matter to your incident management workflow.", "exclusions": [], "id": "01CXX38Q11T19P0K1GFKHUZJ35", "inclusions": [], "name": "Service has an extension or add-on (e.g. Slack, etc.)", "resource_type": "technical_service", "type": "minimum_outbound_integrations" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/standards/update-standard # Update a standard `PUT https://api.pagerduty.com/standards/{id}` Updates a standard Scoped OAuth requires: `standards.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | Id of the standard. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | | | `values` | object | | | | `values.regex` | string | | | | `description` | string | | | | `inclusions` | array of object | | | | `inclusions[].type` | string | | One of: `technical_service_reference`. | | `inclusions[].id` | string | | | | `exclusions` | array of object | | | | `exclusions[].type` | string | | One of: `technical_service_reference`. | | `exclusions[].id` | string | | | Example: Request Example ```json { "active": false } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | | | `description` | string | | | | `id` | string | | | | `name` | string | | | | `type` | string | | | | `resource_type` | string | | One of: `technical_service`. | | `exclusions` | array of object | | | | `exclusions[].type` | string | | One of: `technical_service_reference`. | | `exclusions[].id` | string | | | | `inclusions` | array of object | | | | `inclusions[].type` | string | | One of: `technical_service_reference`. | | `inclusions[].id` | string | | | Example: Response Example ```json { "active": false, "description": "A description provides critical context about what a service represents or is used for to inform team members and responders. The description should be kept concise and understandable by those without deep knowledge of the service.", "exclusions": [], "id": "01CXX38Q0U8XKHO4LNKXUJTBFG", "inclusions": [], "name": "Service has a description", "resource_type": "technical_service", "type": "has_technical_service_description" } ``` ## Response 400 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-dashboards/get-status-dashboard-by-id # Get a single Status Dashboard by `id` `GET https://api.pagerduty.com/status_dashboards/{id}` Get a Status Dashboard by its PagerDuty `id`. Scoped OAuth requires: `status_dashboards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status_dashboard` | object | | | | `status_dashboard.id` | string | | | | `status_dashboard.url_slug` | string | | | | `status_dashboard.name` | string | | | Example: Response Example ```json { "status_dashboard": { "id": "PFCVPS0", "url_slug": "analytics-api", "name": "Analytics API" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-dashboards/get-status-dashboard-by-url-slug # Get a single Status Dashboard by `url_slug` `GET https://api.pagerduty.com/status_dashboards/url_slugs/{url_slug}` Get a Status Dashboard by its PagerDuty `url_slug`. A `url_slug` is a human-readable reference for a custom Status Dashboard that may be created or changed in the UI. It will generally be a `dash-separated-string-like-this`. Scoped OAuth requires: `status_dashboards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `url_slug` | string | yes | The `url_slug` for a status dashboard. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status_dashboard` | object | | | | `status_dashboard.id` | string | | | | `status_dashboard.url_slug` | string | | | | `status_dashboard.name` | string | | | Example: Response Example ```json { "status_dashboard": { "id": "PFCVPS0", "url_slug": "analytics-api", "name": "Analytics API" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-dashboards/get-status-dashboard-service-impacts-by-id # Get impacted Business Services for a Status Dashboard by `id`. `GET https://api.pagerduty.com/status_dashboards/{id}/service_impacts` Get impacted Business Services for a Status Dashboard by `id` This endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted on the specified Status Dashboard up to the limit of 200. The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name. To get Impact information about a specific Business Service on the Status Dashboard that does not appear in the Impact-sorted response, use the `ids[]` parameter on the `/business_services/impacts` endpoint. Scoped OAuth requires: `status_dashboards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `additional_fields[]` | string | | Provides access to additional fields such as highest priority per business service and total impacted count. One of: `services.highest_impacting_priority`, `total_impacted_count`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `services` | array of object | | | | `services[].id` | string | | Read-only. | | `services[].name` | string | | Read-only. | | `services[].type` | string | | The kind of object that has been impacted. One of: `business_service`. | | `services[].status` | string | | The current impact status of the object. One of: `impacted`, `not_impacted`. | | `services[].additional_fields` | object | | | | `services[].additional_fields.highest_impacting_priority` | object \| null | | Priority information for the highest priority level that is affecting the impacted object. | | `services[].additional_fields.highest_impacting_priority.id` | string | | Read-only. | | `services[].additional_fields.highest_impacting_priority.order` | integer | | Read-only. | | `additional_fields` | object | | | | `additional_fields.total_impacted_count` | integer | | | Example: Response Example ```json { "limit": 100, "more": false, "services": [ { "id": "PD1234", "name": "Web API", "type": "business_service", "status": "impacted", "additional_fields": { "highest_impacting_priority": { "id": "PQOMK4S", "order": 128 } } }, { "id": "PF9KMXH", "name": "Analytics Backend", "type": "business_service", "status": "not_impacted", "additional_fields": { "highest_impacting_priority": null } } ], "additional_fields": { "total_impacted_count": 1 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-dashboards/get-status-dashboard-service-impacts-by-url-slug # Get impacted Business Services for a Status Dashboard by `url_slug` `GET https://api.pagerduty.com/status_dashboards/url_slugs/{url_slug}/service_impacts` Get Business Service Impacts for the Business Services on a Status Dashboard by its `url_slug`. A `url_slug` is a human-readable reference for a custom Status Dashboard that may be created or changed in the UI. It will generally be a `dash-separated-string-like-this`. This endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted on the Status Dashboard up to the limit of 200. The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name. To get impact information about a specific Business Service on the Status Dashboard that does not appear in the Impact-sored response, use the `ids[]` parameter on the `/business_services/impacts` endpoint. Scoped OAuth requires: `status_dashboards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `url_slug` | string | yes | The `url_slug` for a status dashboard. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `additional_fields[]` | string | | Provides access to additional fields such as highest priority per business service and total impacted count. One of: `services.highest_impacting_priority`, `total_impacted_count`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `services` | array of object | | | | `services[].id` | string | | Read-only. | | `services[].name` | string | | Read-only. | | `services[].type` | string | | The kind of object that has been impacted. One of: `business_service`. | | `services[].status` | string | | The current impact status of the object. One of: `impacted`, `not_impacted`. | | `services[].additional_fields` | object | | | | `services[].additional_fields.highest_impacting_priority` | object \| null | | Priority information for the highest priority level that is affecting the impacted object. | | `services[].additional_fields.highest_impacting_priority.id` | string | | Read-only. | | `services[].additional_fields.highest_impacting_priority.order` | integer | | Read-only. | | `additional_fields` | object | | | | `additional_fields.total_impacted_count` | integer | | | Example: Response Example ```json { "limit": 100, "more": false, "services": [ { "id": "PD1234", "name": "Web API", "type": "business_service", "status": "impacted", "additional_fields": { "highest_impacting_priority": { "id": "PQOMK4S", "order": 128 } } }, { "id": "PF9KMXH", "name": "Analytics Backend", "type": "business_service", "status": "not_impacted", "additional_fields": { "highest_impacting_priority": null } } ], "additional_fields": { "total_impacted_count": 1 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-dashboards/list-status-dashboards # List Status Dashboards `GET https://api.pagerduty.com/status_dashboards` Get all your account's custom Status Dashboard views. Scoped OAuth requires: `status_dashboards.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | | `status_dashboards` | array of object | | | | `status_dashboards[].id` | string | | | | `status_dashboards[].url_slug` | string | | | | `status_dashboards[].name` | string | | | Example: Response Example ```json { "limit": 100, "next_cursor": null, "status_dashboards": [ { "id": "PFCVPS0", "url_slug": "analytics-api", "name": "Analytics API" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/create-or-update-status-page-postmortem # Create or Update a Post Postmortem `PUT https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/postmortem` Create or Update a Postmortem for a Post by Post ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `postmortem` | object | yes | Request to create/update a given Postmortem resource. | | `postmortem.type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post Postmortem. Read-only. One of: `status_page_post_postmortem`. Default: `status_page_post_postmortem`. | | `postmortem.post` | object | yes | Status Page Post. | | `postmortem.post.id` | string | yes | Status page post unique identifier. | | `postmortem.post.type` | string | | A string that determines the schema of the object. | | `postmortem.message` | string | yes | The message of the Postmortem (supports Rich-Text). Max length: 10000. | | `postmortem.notify_subscribers` | boolean | yes | Whether or not subscribers of the Status Page should be notified about the Postmortem. | Example: default ```json { "postmortem": { "message": "

Something wrong happened and this is a postmortem.

", "notify_subscribers": true, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "type": "status_page_post_postmortem" } } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `postmortem` | object | | A Postmortem represents a communication resource presented in the Status Page about follow-up made to a certain Post. | | `postmortem.id` | string | | An unique identifier within Status Page scope that defines a single Postmortem resource. Read-only. | | `postmortem.self` | string | | The API resource URL of the Postmortem. Read-only. | | `postmortem.post` | object | | Status Page Post. | | `postmortem.post.id` | string | yes | The id of the status page post. | | `postmortem.post.type` | string | | A string that determines the schema of the object. | | `postmortem.message` | string | | The message of the Postmortem (supports Rich-Text). Max length: 10000. | | `postmortem.notify_subscribers` | boolean | | Whether or not subscribers of the Status Page should be notified about the Postmortem. | | `postmortem.reported_at` | string (date-time) | | The date and time the Postmortem was reported. | | `postmortem.type` | string | | The type of the object returned by the API - in this case, a Status Page Post Postmortem. | Example: Response Example ```json { "postmortem": { "id": "PIJ90N7", "message": "

Something wrong happened and this is a postmortem.

", "notify_subscribers": true, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-09-13T10:34:04.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/postmortem", "type": "status_page_post_postmortem" } } ``` ## Response 201 Created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `postmortem` | object | | A Postmortem represents a communication resource presented in the Status Page about follow-up made to a certain Post. Same fields as `postmortem` above. | Example: Response Example ```json { "postmortem": { "id": "PIJ90N7", "message": "

Something wrong happened and this is a postmortem.

", "notify_subscribers": true, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-09-13T10:34:04.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/postmortem", "type": "status_page_post_postmortem" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/create-status-page-post # Create a Status Page Post `POST https://api.pagerduty.com/status_pages/{id}/posts` Create a Post for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `post` | object | yes | Request schema for creating/updating a given Status Page Post resource. | | `post.type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post. One of: `status_page_post`. | | `post.title` | string | yes | The title given to a Post. Min length: 1. Max length: 128. | | `post.post_type` | string | yes | The type of the Post. One of: `incident`, `maintenance`. | | `post.starts_at` | string \| null (date-time) | yes | The date and time the Post intent becomes effective - only for maintenance post type. | | `post.ends_at` | string \| null (date-time) | yes | The date and time the Post intent is concluded - only for maintenance post type. | | `post.updates` | array of object | yes | Post Updates to be associated with a Post. Min items: 1. Max items: 50. | | `post.updates[].self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post.updates[].post` | object | yes | Status Page Post. | | `post.updates[].post.id` | string | yes | Status page post unique identifier. | | `post.updates[].post.type` | string | | A string that determines the schema of the object. | | `post.updates[].message` | string | yes | The message of the Post Update. | | `post.updates[].status` | object | yes | Status Page Status. | | `post.updates[].status.id` | string | yes | Status page Status unique identifier. | | `post.updates[].status.type` | string | | A string that determines the schema of the object. | | `post.updates[].severity` | object | yes | Status Page Severity. | | `post.updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `post.updates[].severity.type` | string | | A string that determines the schema of the object. | | `post.updates[].impacted_services` | array of object | yes | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post.updates[].impacted_services[].service` | object | | Status Page Service. | | `post.updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post.updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post.updates[].impacted_services[].impact` | object | | Status Page Impact. | | `post.updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post.updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post.updates[].update_frequency_ms` | integer \| null | yes | The frequency of the next Post Update in milliseconds. | | `post.updates[].notify_subscribers` | boolean | yes | Determines if the subscribers should be notified of the Post Update. | | `post.updates[].reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post.updates[].type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post Update. | | `post.status_page` | object | yes | Status Page. | | `post.status_page.id` | string | yes | Status page unique identifier. | | `post.status_page.type` | string | | A string that determines the schema of the object. | Example: default ```json { "post": { "ends_at": "2023-12-12T11:00:00.000Z", "post_type": "maintenance", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post", "updates": [ { "impacted_services": [ { "impact": { "id": "PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "type": "status_page_service" } } ], "message": "

Message

", "update_frequency_ms": null, "notify_subscribers": false, "severity": { "id": "PY5OM08", "type": "status_page_severity" }, "status": { "id": "P0400H4", "type": "status_page_status" }, "type": "status_page_post_update" } ] } } ``` ## Response 201 Created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post` | object | | A Post represents a communication resource presented in the Status Page about certain aspects of one or more services associated. | | `post.id` | string | | An unique identifier within Status Page scope that defines a single Post resource. Read-only. | | `post.self` | string | | The API resource URL of the Post. Read-only. | | `post.type` | string | | The type of the object returned by the API - in this case, a Status Page Post. Read-only. Default: `status_page_post`. | | `post.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `post.status_page` | object | | Status Page. | | `post.status_page.id` | string | yes | Status page unique identifier. | | `post.status_page.type` | string | | A string that determines the schema of the object. | | `post.linked_resource` | object | | Linked resource. | | `post.linked_resource.id` | string | yes | Linked resource unique identifier. | | `post.linked_resource.type` | string | | A string that determines the schema of the object. | | `post.postmortem` | object | | Postmortem. | | `post.postmortem.id` | string | yes | Postmortem unique identifier. | | `post.postmortem.type` | string | | A string that determines the schema of the object. | | `post.title` | string | | The title given to a Post. | | `post.starts_at` | string \| null (date-time) | | The date and time the Post intent becomes effective - only for maintenance post type. | | `post.ends_at` | string \| null (date-time) | | The date and time the Post intent is concluded - only for maintenance post type. | | `post.updates` | array of one of: object | | List of status_page_post_update references associated to a Post. Min items: 1. Max items: 50. | | `post.updates[].id` | string | | (StatusPagePostUpdate) The ID of the Post Update. Read-only. | | `post.updates[].self` | string | | (StatusPagePostUpdate) The path to which the Post Update resource is accessible. Read-only. | | `post.updates[].post` | object | | (StatusPagePostUpdate) Status Page Post. | | `post.updates[].post.id` | string | yes | Status page post unique identifier. | | `post.updates[].post.type` | string | | A string that determines the schema of the object. | | `post.updates[].message` | string | | (StatusPagePostUpdate) The message of the Post Update. | | `post.updates[].reviewed_status` | string | | (StatusPagePostUpdate) The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post.updates[].status` | object | | (StatusPagePostUpdate) Status Page Status. | | `post.updates[].status.id` | string | yes | Status page Status unique identifier. | | `post.updates[].status.type` | string | | A string that determines the schema of the object. | | `post.updates[].severity` | object | | (StatusPagePostUpdate) Status Page Severity. | | `post.updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `post.updates[].severity.type` | string | | A string that determines the schema of the object. | | `post.updates[].impacted_services` | array of object | | (StatusPagePostUpdate) Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post.updates[].impacted_services[].service` | object | | Status Page Service. | | `post.updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post.updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post.updates[].impacted_services[].impact` | object | | Status Page Impact. | | `post.updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post.updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post.updates[].update_frequency_ms` | integer \| null | | (StatusPagePostUpdate) The frequency of the next Post Update in milliseconds. | | `post.updates[].notify_subscribers` | boolean | | (StatusPagePostUpdate) Determines if the subscribers should be notified of the Post Update. | | `post.updates[].reported_at` | string \| null (date-time) | | (StatusPagePostUpdate) The date and time the Post Update was reported. | | `post.updates[].type` | string | | (StatusPagePostUpdate) The type of the object returned by the API - in this case, a Status Page Post Update. | Example: default ```json { "post": { "ends_at": "2023-12-12T11:00:00.000Z", "id": "PIJ90N7", "post_type": "maintenance", "postmortem": { "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/postmortem", "type": "status_page_postmortem" }, "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post", "updates": [ { "id": "P7HUBBZ", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/post_updates/P7HUBBZ", "type": "status_page_post_update" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/create-status-page-post-update # Create a Status Page Post Update `POST https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/post_updates` Create a Post Update for a Post by Post ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `post_update` | object | yes | Attributes for Post Update creation/update. | | `post_update.self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_update.post` | object | yes | Status Page Post. | | `post_update.post.id` | string | yes | Status page post unique identifier. | | `post_update.post.type` | string | | A string that determines the schema of the object. | | `post_update.message` | string | yes | The message of the Post Update. | | `post_update.status` | object | yes | Status Page Status. | | `post_update.status.id` | string | yes | Status page Status unique identifier. | | `post_update.status.type` | string | | A string that determines the schema of the object. | | `post_update.severity` | object | yes | Status Page Severity. | | `post_update.severity.id` | string | yes | Status page Severity unique identifier. | | `post_update.severity.type` | string | | A string that determines the schema of the object. | | `post_update.impacted_services` | array of object | yes | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_update.impacted_services[].service` | object | | Status Page Service. | | `post_update.impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_update.impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_update.impacted_services[].impact` | object | | Status Page Impact. | | `post_update.impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_update.impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_update.update_frequency_ms` | integer \| null | yes | The frequency of the next Post Update in milliseconds. | | `post_update.notify_subscribers` | boolean | yes | Determines if the subscribers should be notified of the Post Update. | | `post_update.reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_update.type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: default ```json { "post_update": { "impacted_services": [ { "impact": { "id": "PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "type": "status_page_service" } } ], "message": "

Message

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "type": "status_page_post" }, "severity": { "id": "PY5OM08", "type": "status_page_severity" }, "status": { "id": "P0400H4", "type": "status_page_status" }, "type": "status_page_post_update" } } ``` ## Response 201 Created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post_update` | object | | An update for a Post. | | `post_update.id` | string | | The ID of the Post Update. Read-only. | | `post_update.self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_update.post` | object | | Status Page Post. | | `post_update.post.id` | string | yes | Status page post unique identifier. | | `post_update.post.type` | string | | A string that determines the schema of the object. | | `post_update.message` | string | | The message of the Post Update. | | `post_update.reviewed_status` | string | | The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post_update.status` | object | | Status Page Status. | | `post_update.status.id` | string | yes | Status page Status unique identifier. | | `post_update.status.type` | string | | A string that determines the schema of the object. | | `post_update.severity` | object | | Status Page Severity. | | `post_update.severity.id` | string | yes | Status page Severity unique identifier. | | `post_update.severity.type` | string | | A string that determines the schema of the object. | | `post_update.impacted_services` | array of object | | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_update.impacted_services[].service` | object | | Status Page Service. | | `post_update.impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_update.impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_update.impacted_services[].impact` | object | | Status Page Impact. | | `post_update.impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_update.impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_update.update_frequency_ms` | integer \| null | | The frequency of the next Post Update in milliseconds. | | `post_update.notify_subscribers` | boolean | | Determines if the subscribers should be notified of the Post Update. | | `post_update.reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_update.type` | string | | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: default ```json { "post_update": { "id": "PXSOCH0", "impacted_services": [ { "impact": { "id": "PY5OM08", "self": "https://api.pagerduty.com/status_pages/PR5LMML/impacts/PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/services/PYHMEI3", "type": "status_page_service" } } ], "message": "

We will be undergoing schedule maitenance at this date and time

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-12-12T10:08:19.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/post_updates/PXSOCH0", "severity": { "id": "P6F2CJ4", "self": "https://api.pagerduty.com/status_pages/PR5LMML/severities/P6F2CJ4", "type": "status_page_severity" }, "status": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/statuses/P6F2CJ3", "type": "status_page_status" }, "type": "status_page_post_update", "update_frequency_ms": 300000 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/create-status-page-subscription # Create a Status Page Subscription `POST https://api.pagerduty.com/status_pages/{id}/subscriptions` Create a Subscription for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `subscription` | object | yes | Request schema for creating a StatusPageSubscription. | | `subscription.channel` | string | yes | The channel of the Subscription. One of: `webhook`, `email`. | | `subscription.contact` | string | yes | The subscriber's contact - email address or webhook URL. | | `subscription.status_page` | object | yes | Status Page. | | `subscription.status_page.id` | string | yes | The id of the status page. | | `subscription.status_page.type` | string | | A string that determines the schema of the object. | | `subscription.subscribable_object` | object | yes | The subscribed entity for a given subscription. | | `subscription.subscribable_object.id` | string | | The ID of the subscribed entity for a given subscription. | | `subscription.subscribable_object.type` | string | | The type of the subscribed entity for a given subscription. One of: `status_page`, `status_page_service`, `status_page_post`. | | `subscription.type` | string | yes | A string that determines the schema of the object. | Example: default ```json { "subscription": { "channel": "email", "contact": "joe@email.example", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "subscribable_object": { "id": "PSX4LJI", "type": "status_page_service" }, "type": "status_page_subscription" } } ``` ## Response 201 Created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscription` | object | | A StatusPageSubscription resource represents a subscription to a specific status page entity. | | `subscription.channel` | string | | The channel of the subscription. One of: `webhook`, `email`, `slack`. | | `subscription.contact` | string | | The subscriber's contact - email address, webhook URL, etc... | | `subscription.id` | string | | The ID of the Subscription. | | `subscription.self` | string | | The path in which the Subscription resource is accessible. | | `subscription.status` | string | | The status of the Subscription. One of: `active`, `pending`, `suspended`. | | `subscription.status_page` | object | | Status Page. | | `subscription.status_page.id` | string | yes | Status page unique identifier. | | `subscription.status_page.type` | string | | A string that determines the schema of the object. | | `subscription.subscribable_object` | object | | The subscribed entity for a given subscription. | | `subscription.subscribable_object.id` | string | | The ID of the subscribed entity. | | `subscription.subscribable_object.type` | string | | The type of the subscribed entity. One of: `status_page`, `status_page_service`, `status_page_post`. | | `subscription.type` | string | | A string that determines the schema of the object. | Example: default ```json { "subscription": { "channel": "email", "contact": "address@email.example", "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PIJ90N7/subscriptions/PWZ0PTR", "status": "active", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "subscribable_object": { "id": "PSX4LJI", "type": "status_page_service" }, "type": "status_page_subscription" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/delete-status-page-post # Delete a Status Page Post `DELETE https://api.pagerduty.com/status_pages/{id}/posts/{post_id}` Delete a Post for a Status Page by Status Page ID and Post ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 No Content ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/delete-status-page-post-update # Delete a Status Page Post Update `DELETE https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/post_updates/{post_update_id}` Delete a Post Update for a Post by Post ID and Post Update ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | | `post_update_id` | string | yes | The ID of the Status Page Post Update. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 No Content ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/delete-status-page-postmortem # Delete a Post Postmortem `DELETE https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/postmortem` Delete a Postmortem for a Post by Post ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 No Content ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/delete-status-page-subscription # Delete a Status Page Subscription `DELETE https://api.pagerduty.com/status_pages/{id}/subscriptions/{subscription_id}` Delete a Subscription for a Status Page by Status Page ID and Subscription ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `subscription_id` | string | yes | The ID of the Status Page subscription. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 No Content ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-post-update # Get a Status Page Post Update `GET https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/post_updates/{post_update_id}` Get a Post Update for a Post by Post ID and Post Update ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | | `post_update_id` | string | yes | The ID of the Status Page Post Update. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post_update` | object | | An update for a Post. | | `post_update.id` | string | | The ID of the Post Update. Read-only. | | `post_update.self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_update.post` | object | | Status Page Post. | | `post_update.post.id` | string | yes | Status page post unique identifier. | | `post_update.post.type` | string | | A string that determines the schema of the object. | | `post_update.message` | string | | The message of the Post Update. | | `post_update.reviewed_status` | string | | The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post_update.status` | object | | Status Page Status. | | `post_update.status.id` | string | yes | Status page Status unique identifier. | | `post_update.status.type` | string | | A string that determines the schema of the object. | | `post_update.severity` | object | | Status Page Severity. | | `post_update.severity.id` | string | yes | Status page Severity unique identifier. | | `post_update.severity.type` | string | | A string that determines the schema of the object. | | `post_update.impacted_services` | array of object | | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_update.impacted_services[].service` | object | | Status Page Service. | | `post_update.impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_update.impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_update.impacted_services[].impact` | object | | Status Page Impact. | | `post_update.impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_update.impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_update.update_frequency_ms` | integer \| null | | The frequency of the next Post Update in milliseconds. | | `post_update.notify_subscribers` | boolean | | Determines if the subscribers should be notified of the Post Update. | | `post_update.reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_update.type` | string | | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "post_update": { "id": "PXSOCH0", "impacted_services": [ { "impact": { "id": "PY5OM08", "self": "https://api.pagerduty.com/status_pages/PR5LMML/impacts/PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/services/PYHMEI3", "type": "status_page_service" } } ], "message": "

We will be undergoing schedule maitenance at this date and time

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-12-12T10:08:19.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/post_updates/PXSOCH0", "severity": { "id": "P6F2CJ4", "self": "https://api.pagerduty.com/status_pages/PR5LMML/severities/P6F2CJ4", "type": "status_page_severity" }, "status": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/statuses/P6F2CJ3", "type": "status_page_status" }, "type": "status_page_post_update", "update_frequency_ms": 300000 } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-postmortem # Get a Post Postmortem `GET https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/postmortem` Get a Postmortem for a Post by Post ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `postmortem` | object | | A Postmortem represents a communication resource presented in the Status Page about follow-up made to a certain Post. | | `postmortem.id` | string | | An unique identifier within Status Page scope that defines a single Postmortem resource. Read-only. | | `postmortem.self` | string | | The API resource URL of the Postmortem. Read-only. | | `postmortem.post` | object | | Status Page Post. | | `postmortem.post.id` | string | yes | The id of the status page post. | | `postmortem.post.type` | string | | A string that determines the schema of the object. | | `postmortem.message` | string | | The message of the Postmortem (supports Rich-Text). Max length: 10000. | | `postmortem.notify_subscribers` | boolean | | Whether or not subscribers of the Status Page should be notified about the Postmortem. | | `postmortem.reported_at` | string (date-time) | | The date and time the Postmortem was reported. | | `postmortem.type` | string | | The type of the object returned by the API - in this case, a Status Page Post Postmortem. | Example: Response Example ```json { "postmortem": { "id": "PIJ90N7", "message": "

Something wrong happened and this is a postmortem.

", "notify_subscribers": true, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-09-13T10:34:04.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/postmortem", "type": "status_page_post_postmortem" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-impact # Get a Status Page Impact `GET https://api.pagerduty.com/status_pages/{id}/impacts/{impact_id}` Get an Impact for a Status Page by Status Page ID and Impact ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `impact_id` | string | yes | The ID of the Status Page Impact. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `impact` | object | | A StatusPageImpact resource represents a level of impact for a given Status Page Post. | | `impact.id` | string | | An unique identifier within Status Page scope that defines a Impact entry. Read-only. | | `impact.self` | string | | The API resource URL of the Impact. Read-only. | | `impact.description` | string | | The description is a human-readable text that describes the Impact level. | | `impact.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `impact.status_page` | object | | Status Page. | | `impact.status_page.id` | string | yes | Status page unique identifier. | | `impact.status_page.type` | string | | A string that determines the schema of the object. | | `impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | Example: Response Example ```json { "impact": { "description": "operational", "id": "PIJ90N7", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/impacts/PIJ90N7", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_impact" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-post # Get a Status Page Post `GET https://api.pagerduty.com/status_pages/{id}/posts/{post_id}` Get a Post for a Status Page by Status Page ID and Post ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | array of string | | Array of additional Models to include in response. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post` | object | | A Post represents a communication resource presented in the Status Page about certain aspects of one or more services associated. | | `post.id` | string | | An unique identifier within Status Page scope that defines a single Post resource. Read-only. | | `post.self` | string | | The API resource URL of the Post. Read-only. | | `post.type` | string | | The type of the object returned by the API - in this case, a Status Page Post. Read-only. Default: `status_page_post`. | | `post.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `post.status_page` | object | | Status Page. | | `post.status_page.id` | string | yes | Status page unique identifier. | | `post.status_page.type` | string | | A string that determines the schema of the object. | | `post.linked_resource` | object | | Linked resource. | | `post.linked_resource.id` | string | yes | Linked resource unique identifier. | | `post.linked_resource.type` | string | | A string that determines the schema of the object. | | `post.postmortem` | object | | Postmortem. | | `post.postmortem.id` | string | yes | Postmortem unique identifier. | | `post.postmortem.type` | string | | A string that determines the schema of the object. | | `post.title` | string | | The title given to a Post. | | `post.starts_at` | string \| null (date-time) | | The date and time the Post intent becomes effective - only for maintenance post type. | | `post.ends_at` | string \| null (date-time) | | The date and time the Post intent is concluded - only for maintenance post type. | | `post.updates` | array of one of: object | | List of status_page_post_update references associated to a Post. Min items: 1. Max items: 50. | | `post.updates[].id` | string | | (StatusPagePostUpdate) The ID of the Post Update. Read-only. | | `post.updates[].self` | string | | (StatusPagePostUpdate) The path to which the Post Update resource is accessible. Read-only. | | `post.updates[].post` | object | | (StatusPagePostUpdate) Status Page Post. | | `post.updates[].post.id` | string | yes | Status page post unique identifier. | | `post.updates[].post.type` | string | | A string that determines the schema of the object. | | `post.updates[].message` | string | | (StatusPagePostUpdate) The message of the Post Update. | | `post.updates[].reviewed_status` | string | | (StatusPagePostUpdate) The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post.updates[].status` | object | | (StatusPagePostUpdate) Status Page Status. | | `post.updates[].status.id` | string | yes | Status page Status unique identifier. | | `post.updates[].status.type` | string | | A string that determines the schema of the object. | | `post.updates[].severity` | object | | (StatusPagePostUpdate) Status Page Severity. | | `post.updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `post.updates[].severity.type` | string | | A string that determines the schema of the object. | | `post.updates[].impacted_services` | array of object | | (StatusPagePostUpdate) Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post.updates[].impacted_services[].service` | object | | Status Page Service. | | `post.updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post.updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post.updates[].impacted_services[].impact` | object | | Status Page Impact. | | `post.updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post.updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post.updates[].update_frequency_ms` | integer \| null | | (StatusPagePostUpdate) The frequency of the next Post Update in milliseconds. | | `post.updates[].notify_subscribers` | boolean | | (StatusPagePostUpdate) Determines if the subscribers should be notified of the Post Update. | | `post.updates[].reported_at` | string \| null (date-time) | | (StatusPagePostUpdate) The date and time the Post Update was reported. | | `post.updates[].type` | string | | (StatusPagePostUpdate) The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "post": { "ends_at": "2023-12-12T11:00:00.000Z", "id": "PIJ90N7", "post_type": "maintenance", "postmortem": { "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/postmortem", "type": "status_page_postmortem" }, "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post", "updates": [ { "id": "P7HUBBZ", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/post_updates/P7HUBBZ", "type": "status_page_post_update" } ] } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-service # Get a Status Page Service `GET https://api.pagerduty.com/status_pages/{id}/services/{service_id}` Get a Service for a Status Page by Status Page ID and Service ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `service_id` | string | yes | The ID of the Status Page service. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `service` | object | | A Service represents a PagerDuty service that is linked to a Status Page. | | `service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `service.self` | string | | The API resource URL of the Service. Read-only. | | `service.name` | string | | The name of the Service. | | `service.status_page` | object | | Status Page. | | `service.status_page.id` | string | yes | Status page unique identifier. | | `service.status_page.type` | string | | A string that determines the schema of the object. | | `service.business_service` | object | | Business Service. | | `service.business_service.id` | string | yes | Business Service unique identifier. | | `service.business_service.type` | string | | A string that determines the schema of the object. | | `service.type` | string | | A string that determines the schema of the object. | Example: Response Example ```json { "service": { "business_service": { "id": "P32NFFO", "self": "https://api.pagerduty.com/business_services/P32NFFO", "type": "business_service" }, "id": "PEYSGVF", "name": "Events API (US)", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "type": "status_page_service" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-severity # Get a Status Page Severity `GET https://api.pagerduty.com/status_pages/{id}/severities/{severity_id}` Get a Severity for a Status Page by Status Page ID and Severity ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `severity_id` | string | yes | The ID of the Status Page severity. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `severity` | object | | A Severity represents a level of impact for a given Status Page post. | | `severity.id` | string | | An unique identifier within Status Page scope that defines a Severity entry. Read-only. | | `severity.self` | string | | The API resource URL of the Severity. Read-only. | | `severity.description` | string | | The description is a human-readable text that describes the Severity level. | | `severity.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `severity.status_page` | object | | Status Page. | | `severity.status_page.id` | string | yes | Status page unique identifier. | | `severity.status_page.type` | string | | A string that determines the schema of the object. | | `severity.type` | string | | The type of the object returned by the API - in this case, a Status Page Severity. | Example: Response Example ```json { "severity": { "description": "all good", "id": "PIJ90N7", "post_type": "incident", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_severity" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-status # Get a Status Page Status `GET https://api.pagerduty.com/status_pages/{id}/statuses/{status_id}` Get a Status for a Status Page by Status Page ID and Status ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `status_id` | string | yes | The ID of the Status Page status. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status` | object | | A Status represents a level of undergoing work and/or assessment for a given Status Page post. | | `status.id` | string | | An unique identifier within Status Page scope that defines a Status entry. Read-only. | | `status.self` | string | | The API resource URL of the Status. Read-only. | | `status.description` | string | | The description is a human-readable text that describes the Status level. | | `status.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `status.status_page` | object | | Status Page. | | `status.status_page.id` | string | yes | Status page unique identifier. | | `status.status_page.type` | string | | A string that determines the schema of the object. | | `status.type` | string | | The type of the object returned by the API - in this case, a Status Page Status. | Example: Response Example ```json { "status": { "description": "investigating", "id": "PIJ90N7", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/statuses/PIJ90N7", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_status" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/get-status-page-subscription # Get a Status Page Subscription `GET https://api.pagerduty.com/status_pages/{id}/subscriptions/{subscription_id}` Get a Subscription for a Status Page by Status Page ID and Subscription ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `subscription_id` | string | yes | The ID of the Status Page subscription. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscription` | object | | A StatusPageSubscription resource represents a subscription to a specific status page entity. | | `subscription.channel` | string | | The channel of the subscription. One of: `webhook`, `email`, `slack`. | | `subscription.contact` | string | | The subscriber's contact - email address, webhook URL, etc... | | `subscription.id` | string | | The ID of the Subscription. | | `subscription.self` | string | | The path in which the Subscription resource is accessible. | | `subscription.status` | string | | The status of the Subscription. One of: `active`, `pending`, `suspended`. | | `subscription.status_page` | object | | Status Page. | | `subscription.status_page.id` | string | yes | Status page unique identifier. | | `subscription.status_page.type` | string | | A string that determines the schema of the object. | | `subscription.subscribable_object` | object | | The subscribed entity for a given subscription. | | `subscription.subscribable_object.id` | string | | The ID of the subscribed entity. | | `subscription.subscribable_object.type` | string | | The type of the subscribed entity. One of: `status_page`, `status_page_service`, `status_page_post`. | | `subscription.type` | string | | A string that determines the schema of the object. | Example: Response Example ```json { "subscription": { "channel": "email", "contact": "address@email.example", "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PIJ90N7/subscriptions/PWZ0PTR", "status": "active", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "subscribable_object": { "id": "PSX4LJI", "type": "status_page_service" }, "type": "status_page_subscription" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-impacts # List Status Page Impacts `GET https://api.pagerduty.com/status_pages/{id}/impacts` List Impacts for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `post_type` | string | | Filter by Post type. One of: `incident`, `maintenance`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `impacts` | array of object | | | | `impacts[].id` | string | | An unique identifier within Status Page scope that defines a Impact entry. Read-only. | | `impacts[].self` | string | | The API resource URL of the Impact. Read-only. | | `impacts[].description` | string | | The description is a human-readable text that describes the Impact level. | | `impacts[].post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `impacts[].status_page` | object | | Status Page. | | `impacts[].status_page.id` | string | yes | Status page unique identifier. | | `impacts[].status_page.type` | string | | A string that determines the schema of the object. | | `impacts[].type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | Example: Response Example ```json { "impacts": [ { "description": "operational", "id": "PIJ90N7", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/impacts/PIJ90N7", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_impact" }, { "description": "partial outage", "id": "PF9KMXH", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/impacts/PF9KMXH", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_impact" }, { "description": "outage", "id": "PBAZLIU", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/impacts/PBAZLIU", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_impact" } ], "limit": 25, "more": false, "offset": 0 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-post-updates # List Status Page Post Updates `GET https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/post_updates` List Post Updates for a Status Page by Status Page ID and Post ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `reviewed_status` | string | | Filter by the reviewed status of the Post Update to retrieve. One of: `approved`, `not_reviewed`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `post_updates` | array of object | | | | `post_updates[].id` | string | | The ID of the Post Update. Read-only. | | `post_updates[].self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_updates[].post` | object | | Status Page Post. | | `post_updates[].post.id` | string | yes | Status page post unique identifier. | | `post_updates[].post.type` | string | | A string that determines the schema of the object. | | `post_updates[].message` | string | | The message of the Post Update. | | `post_updates[].reviewed_status` | string | | The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post_updates[].status` | object | | Status Page Status. | | `post_updates[].status.id` | string | yes | Status page Status unique identifier. | | `post_updates[].status.type` | string | | A string that determines the schema of the object. | | `post_updates[].severity` | object | | Status Page Severity. | | `post_updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `post_updates[].severity.type` | string | | A string that determines the schema of the object. | | `post_updates[].impacted_services` | array of object | | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_updates[].impacted_services[].service` | object | | Status Page Service. | | `post_updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_updates[].impacted_services[].impact` | object | | Status Page Impact. | | `post_updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_updates[].update_frequency_ms` | integer \| null | | The frequency of the next Post Update in milliseconds. | | `post_updates[].notify_subscribers` | boolean | | Determines if the subscribers should be notified of the Post Update. | | `post_updates[].reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_updates[].type` | string | | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "post_updates": [ { "id": "PXSOCH0", "impacted_services": [ { "impact": { "id": "PY5OM08", "self": "https://api.pagerduty.com/status_pages/PR5LMML/impacts/PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/services/PYHMEI3", "type": "status_page_service" } } ], "message": "

We will be undergoing schedule maitenance at this date and time

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-12-12T10:08:19.000Z", "reviewed_status": "approved", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/post_updates/PXSOCH0", "severity": { "id": "PY5OM08", "self": "https://api.pagerduty.com/status_pages/PR5LMML/severities/PY5OM08", "type": "status_page_severity" }, "status": { "id": "P0400H4", "self": "https://api.pagerduty.com/status_pages/PR5LMML/statuses/P0400H4", "type": "status_page_status" }, "type": "status_page_post_update" } ], "total": 1 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-posts # List Status Page Posts `GET https://api.pagerduty.com/status_pages/{id}/posts` List Posts for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `post_type` | string | | Filter by Post type. One of: `incident`, `maintenance`. | | `reviewed_status` | string | | Filter by the reviewed status of the Post to retrieve. One of: `approved`, `not_reviewed`. | | `status[]` | array of string | | Filter by an array of Status identifiers. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `posts` | array of object | | | | `posts[].id` | string | | An unique identifier within Status Page scope that defines a single Post resource. Read-only. | | `posts[].self` | string | | The API resource URL of the Post. Read-only. | | `posts[].type` | string | | The type of the object returned by the API - in this case, a Status Page Post. Read-only. Default: `status_page_post`. | | `posts[].post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `posts[].status_page` | object | | Status Page. | | `posts[].status_page.id` | string | yes | Status page unique identifier. | | `posts[].status_page.type` | string | | A string that determines the schema of the object. | | `posts[].linked_resource` | object | | Linked resource. | | `posts[].linked_resource.id` | string | yes | Linked resource unique identifier. | | `posts[].linked_resource.type` | string | | A string that determines the schema of the object. | | `posts[].postmortem` | object | | Postmortem. | | `posts[].postmortem.id` | string | yes | Postmortem unique identifier. | | `posts[].postmortem.type` | string | | A string that determines the schema of the object. | | `posts[].title` | string | | The title given to a Post. | | `posts[].starts_at` | string \| null (date-time) | | The date and time the Post intent becomes effective - only for maintenance post type. | | `posts[].ends_at` | string \| null (date-time) | | The date and time the Post intent is concluded - only for maintenance post type. | | `posts[].updates` | array of one of: object | | List of status_page_post_update references associated to a Post. Min items: 1. Max items: 50. | | `posts[].updates[].id` | string | | (StatusPagePostUpdate) The ID of the Post Update. Read-only. | | `posts[].updates[].self` | string | | (StatusPagePostUpdate) The path to which the Post Update resource is accessible. Read-only. | | `posts[].updates[].post` | object | | (StatusPagePostUpdate) Status Page Post. | | `posts[].updates[].post.id` | string | yes | Status page post unique identifier. | | `posts[].updates[].post.type` | string | | A string that determines the schema of the object. | | `posts[].updates[].message` | string | | (StatusPagePostUpdate) The message of the Post Update. | | `posts[].updates[].reviewed_status` | string | | (StatusPagePostUpdate) The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `posts[].updates[].status` | object | | (StatusPagePostUpdate) Status Page Status. | | `posts[].updates[].status.id` | string | yes | Status page Status unique identifier. | | `posts[].updates[].status.type` | string | | A string that determines the schema of the object. | | `posts[].updates[].severity` | object | | (StatusPagePostUpdate) Status Page Severity. | | `posts[].updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `posts[].updates[].severity.type` | string | | A string that determines the schema of the object. | | `posts[].updates[].impacted_services` | array of object | | (StatusPagePostUpdate) Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `posts[].updates[].impacted_services[].service` | object | | Status Page Service. | | `posts[].updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `posts[].updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `posts[].updates[].impacted_services[].impact` | object | | Status Page Impact. | | `posts[].updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `posts[].updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `posts[].updates[].update_frequency_ms` | integer \| null | | (StatusPagePostUpdate) The frequency of the next Post Update in milliseconds. | | `posts[].updates[].notify_subscribers` | boolean | | (StatusPagePostUpdate) Determines if the subscribers should be notified of the Post Update. | | `posts[].updates[].reported_at` | string \| null (date-time) | | (StatusPagePostUpdate) The date and time the Post Update was reported. | | `posts[].updates[].type` | string | | (StatusPagePostUpdate) The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "posts": [ { "ends_at": "2023-12-12T11:00:00.000Z", "id": "PIJ90N7", "post_type": "maintenance", "postmortem": { "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/postmortem", "type": "status_page_postmortem" }, "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post", "updates": [ { "id": "P7HUBBZ", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/PIJ90N7/post_updates/P7HUBBZ", "type": "status_page_post_update" } ] } ], "total": 3 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-services # List Status Page Services `GET https://api.pagerduty.com/status_pages/{id}/services` List Services for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `services` | array of object | | | | `services[].id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `services[].self` | string | | The API resource URL of the Service. Read-only. | | `services[].name` | string | | The name of the Service. | | `services[].status_page` | object | | Status Page. | | `services[].status_page.id` | string | yes | Status page unique identifier. | | `services[].status_page.type` | string | | A string that determines the schema of the object. | | `services[].business_service` | object | | Business Service. | | `services[].business_service.id` | string | yes | Business Service unique identifier. | | `services[].business_service.type` | string | | A string that determines the schema of the object. | | `services[].type` | string | | A string that determines the schema of the object. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "services": [ { "business_service": { "id": "P32NFFO", "self": "https://api.pagerduty.com/business_services/P32NFFO", "type": "business_service" }, "id": "PEYSGVF", "name": "Events API (US)", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "type": "status_page_service" } ], "total": 1 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-severities # List Status Page Severities `GET https://api.pagerduty.com/status_pages/{id}/severities` List Severities for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `post_type` | string | | Filter by Post type. One of: `incident`, `maintenance`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `severities` | array of object | | | | `severities[].id` | string | | An unique identifier within Status Page scope that defines a Severity entry. Read-only. | | `severities[].self` | string | | The API resource URL of the Severity. Read-only. | | `severities[].description` | string | | The description is a human-readable text that describes the Severity level. | | `severities[].post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `severities[].status_page` | object | | Status Page. | | `severities[].status_page.id` | string | yes | Status page unique identifier. | | `severities[].status_page.type` | string | | A string that determines the schema of the object. | | `severities[].type` | string | | The type of the object returned by the API - in this case, a Status Page Severity. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "severities": [ { "description": "all good", "id": "PIJ90N7", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/severities/PIJ90N7", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_severity" }, { "description": "minor", "id": "PF9KMXH", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/severities/PF9KMXH", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_severity" }, { "description": "major", "id": "PBAZLIU", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/severities/PBAZLIU", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_severity" } ], "total": 3 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-statuses # List Status Page Statuses `GET https://api.pagerduty.com/status_pages/{id}/statuses` List Statuses for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `post_type` | string | | Filter by Post type. One of: `incident`, `maintenance`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `statuses` | array of object | | | | `statuses[].id` | string | | An unique identifier within Status Page scope that defines a Status entry. Read-only. | | `statuses[].self` | string | | The API resource URL of the Status. Read-only. | | `statuses[].description` | string | | The description is a human-readable text that describes the Status level. | | `statuses[].post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `statuses[].status_page` | object | | Status Page. | | `statuses[].status_page.id` | string | yes | Status page unique identifier. | | `statuses[].status_page.type` | string | | A string that determines the schema of the object. | | `statuses[].type` | string | | The type of the object returned by the API - in this case, a Status Page Status. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "statuses": [ { "description": "investigating", "id": "PIJ90N7", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/statuses/PIJ90N7", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_status" }, { "description": "detected", "id": "PF9KMXH", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/statuses/PF9KMXH", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_status" }, { "description": "resolved", "id": "PF9KMXH", "post_type": "incident", "self": "https://api.pagerduty.com/status_pages/PQ8W0D0/statuses/PF9KMXH", "status_page": { "id": "PQ8W0D0", "type": "status_page" }, "type": "status_page_status" } ], "total": 3 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-page-subscriptions # List Status Page Subscriptions `GET https://api.pagerduty.com/status_pages/{id}/subscriptions` List Subscriptions for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `status` | string | | Filter by Subscription status. One of: `active`, `pending`. | | `channel` | string | | Filter by Subscription channel. One of: `webhook`, `email`, `slack`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `subscriptions` | array of object | | | | `subscriptions[].channel` | string | | The channel of the subscription. One of: `webhook`, `email`, `slack`. | | `subscriptions[].contact` | string | | The subscriber's contact - email address, webhook URL, etc... | | `subscriptions[].id` | string | | The ID of the Subscription. | | `subscriptions[].self` | string | | The path in which the Subscription resource is accessible. | | `subscriptions[].status` | string | | The status of the Subscription. One of: `active`, `pending`, `suspended`. | | `subscriptions[].status_page` | object | | Status Page. | | `subscriptions[].status_page.id` | string | yes | Status page unique identifier. | | `subscriptions[].status_page.type` | string | | A string that determines the schema of the object. | | `subscriptions[].subscribable_object` | object | | The subscribed entity for a given subscription. | | `subscriptions[].subscribable_object.id` | string | | The ID of the subscribed entity. | | `subscriptions[].subscribable_object.type` | string | | The type of the subscribed entity. One of: `status_page`, `status_page_service`, `status_page_post`. | | `subscriptions[].type` | string | | A string that determines the schema of the object. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "subscriptions": [ { "channel": "email", "contact": "address@email.example", "id": "PWZ0PTR", "self": "https://api.pagerduty.com/status_pages/PIJ90N7/subscriptions/PWZ0PTR", "status": "active", "status_page": { "id": "PIJ90N7", "type": "status_page" }, "subscribable_object": { "id": "PIJ90N7", "type": "status_page" }, "type": "status_page_susbcription" } ], "total": 1 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/list-status-pages # List Status Pages `GET https://api.pagerduty.com/status_pages` List Status Pages. Scoped OAuth requires: `status_pages.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `status_page_type` | string | | The type of the Status Page. One of: `public`, `private`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `status_pages` | array of object | | | | `status_pages[].id` | string | | An unique identifier within Status Page scope that defines a Status Page entry. Read-only. | | `status_pages[].name` | string | | The name of a Status Page to be presented as a brand title (for example, the rendered Status Page HTML header). Min length: 1. Max length: 125. | | `status_pages[].published_at` | string \| null (date-time) | | The date time moment when a Status Page was published to be publicly available. Read-only. | | `status_pages[].status_page_type` | string | | The type of Status Pages to retrieve - public is accessible to everyone on the internet or private requiring some sort of authentication/authorization layer. One of: `public`, `private`. | | `status_pages[].url` | string (url) | | The URL from which the Status Page can be accessed on the internet (either customer's domain or default *.trust.pagerduty.com). | | `status_pages[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by _reference if the object is a reference. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "status_pages": [ { "id": "PT4KHLK", "name": "My brand Status Page", "published_at": "2017-09-13T10:11:12.000Z", "status_page_type": "private", "type": "status_page", "url": "https://status.mybrand.example" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/update-status-page-post # Update a Status Page Post `PUT https://api.pagerduty.com/status_pages/{id}/posts/{post_id}` Update a Post for a Status Page by Status Page ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `post` | object | yes | Request schema for creating a given Status Page Post resource. | | `post.type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post. One of: `status_page_post`. | | `post.title` | string | yes | The title given to a Post. Min length: 1. Max length: 128. | | `post.post_type` | string | yes | The type of the Post. One of: `incident`, `maintenance`. | | `post.starts_at` | string \| null (date-time) | yes | The date and time the Post intent becomes effective - only for maintenance post type. | | `post.ends_at` | string \| null (date-time) | yes | The date and time the Post intent is concluded - only for maintenance post type. | | `post.status_page` | object | yes | Status Page. | | `post.status_page.id` | string | yes | Status page unique identifier. | | `post.status_page.type` | string | | A string that determines the schema of the object. | Example: default ```json { "post": { "ends_at": "2023-12-12T11:00:00.000Z", "post_type": "maintenance", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post" } } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post` | object | | A Post represents a communication resource presented in the Status Page about certain aspects of one or more services associated. | | `post.id` | string | | An unique identifier within Status Page scope that defines a single Post resource. Read-only. | | `post.self` | string | | The API resource URL of the Post. Read-only. | | `post.type` | string | | The type of the object returned by the API - in this case, a Status Page Post. Read-only. Default: `status_page_post`. | | `post.post_type` | string | | The type of the Post. One of: `incident`, `maintenance`. | | `post.status_page` | object | | Status Page. | | `post.status_page.id` | string | yes | Status page unique identifier. | | `post.status_page.type` | string | | A string that determines the schema of the object. | | `post.linked_resource` | object | | Linked resource. | | `post.linked_resource.id` | string | yes | Linked resource unique identifier. | | `post.linked_resource.type` | string | | A string that determines the schema of the object. | | `post.postmortem` | object | | Postmortem. | | `post.postmortem.id` | string | yes | Postmortem unique identifier. | | `post.postmortem.type` | string | | A string that determines the schema of the object. | | `post.title` | string | | The title given to a Post. | | `post.starts_at` | string \| null (date-time) | | The date and time the Post intent becomes effective - only for maintenance post type. | | `post.ends_at` | string \| null (date-time) | | The date and time the Post intent is concluded - only for maintenance post type. | | `post.updates` | array of one of: object | | List of status_page_post_update references associated to a Post. Min items: 1. Max items: 50. | | `post.updates[].id` | string | | (StatusPagePostUpdate) The ID of the Post Update. Read-only. | | `post.updates[].self` | string | | (StatusPagePostUpdate) The path to which the Post Update resource is accessible. Read-only. | | `post.updates[].post` | object | | (StatusPagePostUpdate) Status Page Post. | | `post.updates[].post.id` | string | yes | Status page post unique identifier. | | `post.updates[].post.type` | string | | A string that determines the schema of the object. | | `post.updates[].message` | string | | (StatusPagePostUpdate) The message of the Post Update. | | `post.updates[].reviewed_status` | string | | (StatusPagePostUpdate) The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post.updates[].status` | object | | (StatusPagePostUpdate) Status Page Status. | | `post.updates[].status.id` | string | yes | Status page Status unique identifier. | | `post.updates[].status.type` | string | | A string that determines the schema of the object. | | `post.updates[].severity` | object | | (StatusPagePostUpdate) Status Page Severity. | | `post.updates[].severity.id` | string | yes | Status page Severity unique identifier. | | `post.updates[].severity.type` | string | | A string that determines the schema of the object. | | `post.updates[].impacted_services` | array of object | | (StatusPagePostUpdate) Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post.updates[].impacted_services[].service` | object | | Status Page Service. | | `post.updates[].impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post.updates[].impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post.updates[].impacted_services[].impact` | object | | Status Page Impact. | | `post.updates[].impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post.updates[].impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post.updates[].update_frequency_ms` | integer \| null | | (StatusPagePostUpdate) The frequency of the next Post Update in milliseconds. | | `post.updates[].notify_subscribers` | boolean | | (StatusPagePostUpdate) Determines if the subscribers should be notified of the Post Update. | | `post.updates[].reported_at` | string \| null (date-time) | | (StatusPagePostUpdate) The date and time the Post Update was reported. | | `post.updates[].type` | string | | (StatusPagePostUpdate) The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "post": { "ends_at": "2023-12-12T11:00:00.000Z", "post_type": "maintenance", "starts_at": "2023-12-12T11:00:00.000Z", "status_page": { "id": "PR5LMML", "type": "status_page" }, "title": "maintenance window for database upgrade", "type": "status_page_post", "updates": [ { "impacted_services": [ { "impact": { "id": "PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "type": "status_page_service" } } ], "message": "

Message

", "update_frequency_ms": null, "notify_subscribers": false, "severity": { "id": "PY5OM08", "type": "status_page_severity" }, "status": { "id": "P0400H4", "type": "status_page_status" }, "type": "status_page_post_update" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/status-pages/update-status-page-post-update # Update a Status Page Post Update `PUT https://api.pagerduty.com/status_pages/{id}/posts/{post_id}/post_updates/{post_update_id}` Update a Post Update for a Post by Post ID and Post Update ID. Scoped OAuth requires: `status_pages.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `post_id` | string | yes | The ID of the Status Page Post. | | `post_update_id` | string | yes | The ID of the Status Page Post Update. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `post_update` | object | yes | Attributes for Post Update creation/update. | | `post_update.self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_update.post` | object | yes | Status Page Post. | | `post_update.post.id` | string | yes | Status page post unique identifier. | | `post_update.post.type` | string | | A string that determines the schema of the object. | | `post_update.message` | string | yes | The message of the Post Update. | | `post_update.status` | object | yes | Status Page Status. | | `post_update.status.id` | string | yes | Status page Status unique identifier. | | `post_update.status.type` | string | | A string that determines the schema of the object. | | `post_update.severity` | object | yes | Status Page Severity. | | `post_update.severity.id` | string | yes | Status page Severity unique identifier. | | `post_update.severity.type` | string | | A string that determines the schema of the object. | | `post_update.impacted_services` | array of object | yes | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_update.impacted_services[].service` | object | | Status Page Service. | | `post_update.impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_update.impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_update.impacted_services[].impact` | object | | Status Page Impact. | | `post_update.impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_update.impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_update.update_frequency_ms` | integer \| null | yes | The frequency of the next Post Update in milliseconds. | | `post_update.notify_subscribers` | boolean | yes | Determines if the subscribers should be notified of the Post Update. | | `post_update.reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_update.type` | string | yes | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: default ```json { "post_update": { "impacted_services": [ { "impact": { "id": "PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "type": "status_page_service" } } ], "message": "

Message

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "type": "status_page_post" }, "severity": { "id": "PY5OM08", "type": "status_page_severity" }, "status": { "id": "P0400H4", "type": "status_page_status" }, "type": "status_page_post_update" } } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `post_update` | object | | An update for a Post. | | `post_update.id` | string | | The ID of the Post Update. Read-only. | | `post_update.self` | string | | The path to which the Post Update resource is accessible. Read-only. | | `post_update.post` | object | | Status Page Post. | | `post_update.post.id` | string | yes | Status page post unique identifier. | | `post_update.post.type` | string | | A string that determines the schema of the object. | | `post_update.message` | string | | The message of the Post Update. | | `post_update.reviewed_status` | string | | The status of the Post Updates to retrieve. One of: `approved`, `not_reviewed`. | | `post_update.status` | object | | Status Page Status. | | `post_update.status.id` | string | yes | Status page Status unique identifier. | | `post_update.status.type` | string | | A string that determines the schema of the object. | | `post_update.severity` | object | | Status Page Severity. | | `post_update.severity.id` | string | yes | Status page Severity unique identifier. | | `post_update.severity.type` | string | | A string that determines the schema of the object. | | `post_update.impacted_services` | array of object | | Impacted services represent the status page services affected by a post update, and its impact. Min items: 0. | | `post_update.impacted_services[].service` | object | | Status Page Service. | | `post_update.impacted_services[].service.id` | string | | An unique identifier within Status Page scope that defines a Service entry. Read-only. | | `post_update.impacted_services[].service.type` | string | | The type of the object returned by the API - in this case, a Status Page Service. | | `post_update.impacted_services[].impact` | object | | Status Page Impact. | | `post_update.impacted_services[].impact.id` | string | | An unique identifier within Status Page scope that defines a Status Page Impact entry. Read-only. | | `post_update.impacted_services[].impact.type` | string | | The type of the object returned by the API - in this case, a Status Page Impact. | | `post_update.update_frequency_ms` | integer \| null | | The frequency of the next Post Update in milliseconds. | | `post_update.notify_subscribers` | boolean | | Determines if the subscribers should be notified of the Post Update. | | `post_update.reported_at` | string \| null (date-time) | | The date and time the Post Update was reported. | | `post_update.type` | string | | The type of the object returned by the API - in this case, a Status Page Post Update. | Example: Response Example ```json { "post_update": { "id": "PXSOCH0", "impacted_services": [ { "impact": { "id": "PY5OM08", "self": "https://api.pagerduty.com/status_pages/PR5LMML/impacts/PY5OM08", "type": "status_page_impact" }, "service": { "id": "PYHMEI3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/services/PYHMEI3", "type": "status_page_service" } } ], "message": "

We will be undergoing schedule maitenance at this date and time

", "notify_subscribers": false, "post": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3", "type": "status_page_post" }, "reported_at": "2023-12-12T10:08:19.000Z", "self": "https://api.pagerduty.com/status_pages/PR5LMML/posts/P6F2CJ3/post_updates/PXSOCH0", "severity": { "id": "P6F2CJ4", "self": "https://api.pagerduty.com/status_pages/PR5LMML/severities/P6F2CJ4", "type": "status_page_severity" }, "status": { "id": "P6F2CJ3", "self": "https://api.pagerduty.com/status_pages/PR5LMML/statuses/P6F2CJ3", "type": "status_page_status" }, "type": "status_page_post_update", "update_frequency_ms": 300000 } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/create-entity-type-by-id-change-tags # Assign tags `POST https://api.pagerduty.com/{entity_type}/{id}/change_tags` Assign existing or new tags. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `entity_type` | string | yes | Type of entity related with the tag. One of: `users`, `teams`, `escalation_policies`. | | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `add` | array of object | | Array of tags and/or tag references to add to the entity. For elements with type `tag_reference`, the tag with the corresponding `id` is added to the entity. For elements with type `tag`, if there is an existing tag with the given label that tag is added to the entity. If there is no existing tag with that label and the user has permission to create tags, a new tag is created with that label and assigned to the entity. | | `add[].type` | string | yes | One of: `tag`, `tag_reference`. | | `add[].label` | string | | The label of the tag. Should be used when type is "tag". Max length: 191. | | `add[].id` | string | | The id of the tag. Should be used when type is "tag_reference". Read-only. | | `remove` | array of object | | Array of tag references to remove from the entity. | | `remove[].type` | string | yes | One of: `tag_reference`. | | `remove[].id` | string | yes | The id of the tag. Read-only. | Example: Request Example ```json { "add": [ { "type": "tag", "label": "Batman" }, { "type": "tag_reference", "id": "P5IYCNZ" } ], "remove": [ { "type": "tag_reference", "id": "POE7RY8" }, { "type": "tag_reference", "id": "PG68P1M" } ] } ``` ## Response 200 The tags were added and/or removed. ### `application/json` Type: object Example: Request Example ```json { "add": [ { "type": "tag", "label": "Batman" }, { "type": "tag_reference", "id": "P5IYCNZ" } ], "remove": [ { "type": "tag_reference", "id": "POE7RY8" }, { "type": "tag_reference", "id": "PG68P1M" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/create-tags # Create a tag `POST https://api.pagerduty.com/tags` Create a Tag. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `tag` | object | yes | | | `tag.id` | string | | Read-only. | | `tag.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `tag.type` | string | yes | The type of object being created. One of: `tag`. Default: `tag`. | | `tag.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `tag.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `tag.label` | string | yes | The label of the tag. Max length: 191. | Example: Request Example ```json { "tag": { "type": "tag", "label": "Batman" } } ``` ## Response 201 The tag that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `tag` | object | yes | Same fields as `tag` above. | Example: Response Example ```json { "tag": { "type": "tag", "summary": "Batman", "self": "https://api.pagerduty.com/tags/P5IYCNZ", "label": "Batman", "id": "P5IYCNZ", "html_url": null } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/delete-tag # Delete a tag `DELETE https://api.pagerduty.com/tags/{id}` Remove an existing Tag. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The tag was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/get-entity-type-by-id-tags # Get tags for entities `GET https://api.pagerduty.com/{entity_type}/{id}/tags` Get related tags for Users, Teams or Escalation Policies. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `entity_type` | string | yes | Type of entity related with the tag. One of: `users`, `teams`, `escalation_policies`. | | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of tags. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `tags` | array of object | yes | | | `tags[].id` | string | | Read-only. | | `tags[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `tags[].type` | string | yes | The type of object being created. One of: `tag`. Default: `tag`. | | `tags[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `tags[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `tags[].label` | string | yes | The label of the tag. Max length: 191. | Example: Response Example ```json { "tags": [ { "type": "tag", "summary": "Batman", "self": "https://api.pagerduty.com/tags/P5IYCNZ", "label": "Batman", "id": "P5IYCNZ", "html_url": null } ], "limit": 100, "offset": 0, "total": 1, "more": false } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/get-tag # Get a tag `GET https://api.pagerduty.com/tags/{id}` Get details about an existing Tag. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The tag requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `tag` | object | yes | | | `tag.id` | string | | Read-only. | | `tag.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `tag.type` | string | yes | The type of object being created. One of: `tag`. Default: `tag`. | | `tag.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `tag.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `tag.label` | string | yes | The label of the tag. Max length: 191. | Example: Response Example ```json { "tag": { "type": "tag", "summary": "Batman", "self": "https://api.pagerduty.com/tags/P5IYCNZ", "label": "Batman", "id": "P5IYCNZ", "html_url": null } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/get-tags-by-entity-type # Get connected entities `GET https://api.pagerduty.com/tags/{id}/{entity_type}` Get related Users, Teams or Escalation Policies for the Tag. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `entity_type` | string | yes | Type of entity related with the tag. One of: `users`, `teams`, `escalation_policies`. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of connected entities. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `users` | array of object | | | | `users[].id` | string | yes | Read-only. | | `users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].type` | string | yes | One of: `user_reference`, `team_reference`, `escalation_policy_reference`. | | `users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `teams` | array of object | | | | `teams[].id` | string | yes | Read-only. | | `teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `teams[].type` | string | yes | One of: `user_reference`, `team_reference`, `escalation_policy_reference`. | | `teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `escalation_policies` | array of object | | | | `escalation_policies[].id` | string | yes | Read-only. | | `escalation_policies[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `escalation_policies[].type` | string | yes | One of: `user_reference`, `team_reference`, `escalation_policy_reference`. | | `escalation_policies[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `escalation_policies[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "users": [ { "id": "PXPGF42", "type": "user_reference" }, { "id": "PAM4FGS", "type": "user_reference" } ], "limit": 100, "offset": 0, "total": 2, "more": false } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/tags/list-tags # List tags `GET https://api.pagerduty.com/tags` List all of your account's tags. A Tag is applied to Escalation Policies, Teams or Users and can be used to filter them. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#tags) Scoped OAuth requires: `tags.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the tags whose label matches the query. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of tags names. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `tags` | array of object | yes | | | `tags[].id` | string | | Read-only. | | `tags[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `tags[].type` | string | yes | The type of object being created. One of: `tag`. Default: `tag`. | | `tags[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `tags[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `tags[].label` | string | yes | The label of the tag. Max length: 191. | Example: Response Example ```json { "tags": [ { "type": "tag", "summary": "Batman", "self": "https://api.pagerduty.com/tags/P5IYCNZ", "label": "Batman", "id": "P5IYCNZ", "html_url": null } ], "limit": 100, "offset": 0, "total": 1, "more": false } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/create-team # Create a team `POST https://api.pagerduty.com/teams` Create a new Team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The team to be created. | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | | | `team.id` | string | | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | The type of object being created. One of: `team`. Default: `team`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `team.name` | string | yes | The name of the team. Max length: 100. | | `team.description` | string | | The description of the team. Max length: 1024. | | `team.default_role` | string | | The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | Example: Request Example ```json { "team": { "type": "team", "name": "Engineering", "description": "The engineering team" } } ``` ## Response 201 The team that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | Same fields as `team` above. | Example: Response Example ```json { "team": { "id": "PQ9K7I8", "type": "team", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8", "name": "Engineering", "description": "All engineering", "default_role": "manager" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/create-team-notification-subscriptions # Create Team Notification Subscriptions `POST https://api.pagerduty.com/teams/{id}/notification_subscriptions` Create new Notification Subscriptions for the given Team. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to subscribe to. | Field | Type | Required | Description | |---|---|---|---| | `subscribables` | array of object | yes | Min items: 1. Items must be unique. | | `subscribables[].subscribable_id` | string | | The ID of the entity to subscribe to. | | `subscribables[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | Example: Request Example ```json { "subscribables": [ { "subscribable_type": "incident", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1235" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscriptions` | array of object | | | | `subscriptions[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].account_id` | string | | The type of the entity being subscribed to. | | `subscriptions[].result` | string | | The resulting status of the subscription. One of: `success`, `duplicate`, `unauthorized`. | Example: Response Example ```json { "subscriptions": [ { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "success" }, { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "duplicate" }, { "account_id": "PD1234", "subscribable_id": "PD1235", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "team", "result": "unauthorized" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/delete-team # Delete a team `DELETE https://api.pagerduty.com/teams/{id}` Remove an existing team. Succeeds only if the team has no associated Escalation Policies, Services, Schedules and Subteams. All associated unresovled incidents will be reassigned to another team (if specified) or will loose team association, thus becoming account-level (with visibility implications). Note that the incidents reassignment process is asynchronous and has no guarantee to complete before the API call return. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `reassignment_team` | string | | Team to reassign unresolved incident to. If an unresolved incident exists on both the reassignment team and the team being deleted, a duplicate will not be made. If not supplied, unresolved incidents will be made account-level. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The team was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/delete-team-escalation-policy # Remove an escalation policy from a team `DELETE https://api.pagerduty.com/teams/{id}/escalation_policies/{escalation_policy_id}` Remove an escalation policy from a team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `escalation_policy_id` | string | yes | The escalation policy ID on the team. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The escalation policy was removed from the team. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/delete-team-user # Remove a user from a team `DELETE https://api.pagerduty.com/teams/{id}/users/{user_id}` Remove a user from a team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `user_id` | string | yes | The user ID on the team. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The user was removed to the team. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/get-team # Get a team `GET https://api.pagerduty.com/teams/{id}` Get details about an existing team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. One of: `privileges`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The team requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | | | `team.id` | string | | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | The type of object being created. One of: `team`. Default: `team`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `team.name` | string | yes | The name of the team. Max length: 100. | | `team.description` | string | | The description of the team. Max length: 1024. | | `team.default_role` | string | | The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | Example: Response Example ```json { "team": { "id": "PQ9K7I8", "type": "team", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8", "name": "Engineering", "description": "All engineering", "default_role": "manager" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/get-team-notification-subscriptions # List Team Notification Subscriptions `GET https://api.pagerduty.com/teams/{id}/notification_subscriptions` Retrieve a list of Notification Subscriptions the given Team has. > Teams must be added through `POST /teams/{id}/notification_subscriptions` to be returned from this endpoint. Scoped OAuth requires: `subscribers.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `subscriptions` | array of object | yes | | | `subscriptions[].subscription` | object | | An object describing the relationship of a NotificationSubscriber and a NotificationSubscribable. | | `subscriptions[].subscription.subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscription.subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscription.subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscription.subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].subscription.account_id` | string | | The ID of the account belonging to the subscriber entity. | | `subscriptions[].subscribable_name` | string \| null | | The name of the subscribable. | Example: Response Example ```json { "subscriptions": [ { "subscription": { "subscriber_id": "PD1234", "subscriber_type": "team", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscribable_name": null, "account_id": "PD1234" } }, { "subscription": { "subscriber_id": "PD1234", "subscriber_type": "team", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscribable_name": "Online Payment", "account_id": "PD1234" } } ], "limit": 2, "offset": 0, "total": 1000, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/list-team-users # List members of a team `GET https://api.pagerduty.com/teams/{id}/members` Get information about members on a team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `users`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of users within the requested team. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `members` | array of object | | | | `members[].user` | object | | | | `members[].user.id` | string | yes | Read-only. | | `members[].user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `members[].user.type` | string | yes | One of: `user_reference`. | | `members[].user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `members[].user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `members[].role` | string | | | Example: Response Example ```json { "members": [ { "user": { "id": "P0XJYI9", "type": "user_reference", "summary": "Jane Doe", "self": "https://api.pagerduty.com/users/P0XJYI9", "html_url": "https://subdomain.pagerduty.com/users/P0XJYI9" }, "role": "manager" } ], "limit": 100, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/list-teams # List teams `GET https://api.pagerduty.com/teams` List teams of your PagerDuty account, optionally filtered by a search query. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Filters the result, showing only the records whose name matches the query. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of teams. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `teams` | array of object | yes | | | `teams[].id` | string | | Read-only. | | `teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `teams[].type` | string | yes | The type of object being created. One of: `team`. Default: `team`. | | `teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `teams[].name` | string | yes | The name of the team. Max length: 100. | | `teams[].description` | string | | The description of the team. Max length: 1024. | | `teams[].default_role` | string | | The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | Example: Response Example ```json { "teams": [ { "id": "PQ9K7I8", "type": "team", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8", "name": "Engineering", "description": "All engineering" } ], "limit": 100, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/list-teams-audit-records # List audit records for a team `GET https://api.pagerduty.com/teams/{id}/audit/records` The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PDRECORD_USER_ROLE_ON_TEAM", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "111lDEOIH-534-4ljhLHJjh111", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "method": { "type": "browser" }, "root_resource": { "id": "PD_TEAM123", "type": "team_reference", "summary": "my DevOps team", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" }, "action": "update", "details": { "resource": { "id": "PD_ADMIN_USER123", "type": "user_reference", "summary": "AA Admin User", "self": "https://api.pagerduty.com/users/PD_ADMIN_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_ADMIN_USER123" }, "fields": [ { "name": "members.role", "value": "manager" } ] } }, { "id": "PDRECORD_USER_ADDED_TO_TEAM", "execution_time": "2020-06-04T15:30:16.272Z", "execution_context": { "request_id": "111lDEOIH-534-4ljhLHJjh111", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "method": { "type": "browser" }, "root_resource": { "id": "PD_TEAM123", "type": "team_reference", "summary": "DevOps" }, "action": "update", "details": { "resource": { "id": "PD_TEAM123", "type": "team_reference", "summary": "DevOps" }, "references": [ { "name": "members", "added": [ { "id": "PD_ADMIN_USER123", "type": "user_reference", "summary": "AA Admin User", "self": "https://api.pagerduty.com/users/PD_ADMIN_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_ADMIN_USER123" } ] } ] } }, { "id": "PDRECORD_TEAM_CREATED", "execution_time": "2020-06-04T15:25:04.113Z", "execution_context": { "request_id": "222lDEOIH-534-4ljhLHJjh222", "remote_address": "201.19.20.19" }, "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "method": { "type": "browser" }, "root_resource": { "id": "PD_TEAM123", "type": "team_reference", "summary": "DevOps", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" }, "action": "create", "details": { "resource": { "id": "PD_TEAM123", "type": "team_reference", "summary": "DevOps", "self": "https://api.pagerduty.com/teams/PD_TEAM123", "html_url": "https://mydomain.pagerduty.com/teams/PD_TEAM123" }, "fields": [ { "name": "name", "value": "DevOps" }, { "name": "description", "value": "MyDevOps Team" }, { "name": "default_role", "value": "manager" } ] } } ], "next_cursor": null, "limit": 10 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/remove-team-notification-subscriptions # Remove Team Notification Subscriptions `POST https://api.pagerduty.com/teams/{id}/notification_subscriptions/unsubscribe` Unsubscribe the given Team from Notifications on the matching Subscribable entities. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to unsubscribe from. | Field | Type | Required | Description | |---|---|---|---| | `subscribables` | array of object | yes | Min items: 1. Items must be unique. | | `subscribables[].subscribable_id` | string | | The ID of the entity to subscribe to. | | `subscribables[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | Example: Response Example ```json { "subscribables": [ { "subscribable_type": "incident", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1234" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `deleted_count` | number | yes | | | `unauthorized_count` | number | yes | | | `non_existent_count` | number | yes | | Example: Response Example ```json { "deleted_count": 1, "unauthorized_count": 1, "non_existent_count": 0 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/update-team # Update a team `PUT https://api.pagerduty.com/teams/{id}` Update an existing team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The team to be updated. | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | | | `team.id` | string | | Read-only. | | `team.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `team.type` | string | yes | The type of object being created. One of: `team`. Default: `team`. | | `team.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `team.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `team.name` | string | yes | The name of the team. Max length: 100. | | `team.description` | string | | The description of the team. Max length: 1024. | | `team.default_role` | string | | The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager"). One of: `manager`, `none`. Default: `manager`. | Example: Request Example ```json { "team": { "type": "team", "name": "Engineering", "description": "The engineering team" } } ``` ## Response 200 The team that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `team` | object | yes | Same fields as `team` above. | Example: Response Example ```json { "team": { "id": "PQ9K7I8", "type": "team", "summary": "Engineering", "self": "https://api.pagerduty.com/teams/PQ9K7I8", "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8", "name": "Engineering", "description": "All engineering", "default_role": "manager" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/update-team-escalation-policy # Add an escalation policy to a team `PUT https://api.pagerduty.com/teams/{id}/escalation_policies/{escalation_policy_id}` Add an escalation policy to a team. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `escalation_policy_id` | string | yes | The escalation policy ID on the team. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The escalation policy was added to the team. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/teams/update-team-user # Add a user to a team `PUT https://api.pagerduty.com/teams/{id}/users/{user_id}` Add a user to a team. Attempting to add a user with the `read_only_user` role will return a 400 error. A team is a collection of Users and Escalation Policies that represent a group of people within an organization. For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#teams) Scoped OAuth requires: `teams.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `user_id` | string | yes | The user ID on the team. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The role of the user on the team. | Field | Type | Required | Description | |---|---|---|---| | `role` | string | | The role of the user on the team. One of: `observer`, `responder`, `manager`. | Example: Request Example ```json { "role": "observer" } ``` ## Response 204 The user was added to the team. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/create-template # Create a template `POST https://api.pagerduty.com/templates` Create a new template Scoped OAuth requires: `templates.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `template` | object | yes | | | `template.template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `template.name` | string | | The name of the template. | | `template.description` | string \| null | | Description of the template. | | `template.templated_fields` | object | | | | `template.templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `template.templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `template.templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | Example: Request Example ```json { "template": { "description": "Sample template description", "templated_fields": { "email_body": "
sample
", "email_subject": "Sample email Subject", "message": "Sample SMS message" }, "name": "Sample Template", "template_type": "status_update" } } ``` ## Response 201 Template successfully created ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `template` | object | yes | | | `template.template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `template.name` | string | | The name of the template. | | `template.description` | string \| null | | Description of the template. | | `template.templated_fields` | object | | | | `template.templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `template.templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `template.templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | | `template.id` | string | | Read-only. | | `template.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `template.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.type` | string | | One of: `template`. | | `template.created_by` | one of: object \| object | | User/Account object reference of the creator. | | `template.created_by.id` | string | yes | (option 1) Read-only. | | `template.created_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.created_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.created_by.id` | string | yes | (option 2) Read-only. | | `template.created_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.created_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by` | one of: object \| object | | User/Account object reference of the updator. | | `template.updated_by.id` | string | yes | (option 1) Read-only. | | `template.updated_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by.id` | string | yes | (option 2) Read-only. | | `template.updated_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "template": { "created_at": "2022-08-19T13:46:22Z", "created_by": { "id": "PF9KMXH", "self": "https://api.pagerduty.com/users/PF9KMXH", "type": "user_reference" }, "description": "Sample template description", "templated_fields": { "email_body": "
sample
", "email_subject": "Sample email Subject", "message": "Sample SMS message" }, "id": "PCCR863", "name": "Sample Template", "self": "https://api.pagerduty.com/templates/PCCR863", "template_type": "status_update", "type": "template", "updated_at": "2022-08-19T13:46:22Z", "updated_by": { "id": "PF9KMXH", "self": "https://api.pagerduty.com/users/PF9KMXH", "type": "user_reference" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/delete-template # Delete a template `DELETE https://api.pagerduty.com/templates/{id}` Delete a specific of templates on the account Scoped OAuth requires: `templates.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Response 204 Successful operation ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/get-template # Get a template `GET https://api.pagerduty.com/templates/{id}` Get a single template on the account Scoped OAuth requires: `templates.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Response 200 Successful operation ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `template` | object | yes | | | `template.template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `template.name` | string | | The name of the template. | | `template.description` | string \| null | | Description of the template. | | `template.templated_fields` | object | | | | `template.templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `template.templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `template.templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | | `template.id` | string | | Read-only. | | `template.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `template.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.type` | string | | One of: `template`. | | `template.created_by` | one of: object \| object | | User/Account object reference of the creator. | | `template.created_by.id` | string | yes | (option 1) Read-only. | | `template.created_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.created_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.created_by.id` | string | yes | (option 2) Read-only. | | `template.created_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.created_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by` | one of: object \| object | | User/Account object reference of the updator. | | `template.updated_by.id` | string | yes | (option 1) Read-only. | | `template.updated_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by.id` | string | yes | (option 2) Read-only. | | `template.updated_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "template": { "created_at": "2022-12-30T16:00:00Z", "created_by": { "id": "PDZR4CN", "self": "https://api.pagerduty.com/users/PDZR4CN", "type": "user_reference" }, "description": "Sample template description", "templated_fields": { "email_body": "
sample
", "email_subject": "Sample email Subject", "message": "Sample template message" }, "id": "PBZUP2B", "name": "Sample Template 160", "self": "https://api.pagerduty.com/templates/PBZUP2B", "template_type": "status_update", "type": "template", "updated_at": "2022-12-30T16:00:00Z", "updated_by": { "id": "PGY287N", "self": "https://api.pagerduty.com/users/PGY287N", "type": "user_reference" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/get-template-fields # List template fields `GET https://api.pagerduty.com/templates/fields` Get a list of fields that can be used on the account templates. Scoped OAuth requires: `templates.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 An array of template fields. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `fields` | array of object | yes | | | `fields[].data_type` | string | | The kind of data the template field is allowed to contain. One of: `boolean`, `integer`, `float`, `string`, `datetime`, `url`. | | `fields[].default_value` | string \| null | | The default value of the template field. | | `fields[].description` | string \| null | | A short description of the template field. | | `fields[].domain_name` | object | | | | `fields[].domain_name.order` | integer | | | | `fields[].domain_name.summary` | string | | | | `fields[].keyword` | string \| null | | | | `fields[].summary` | string | | A short summary of the template field. | | `fields[].type` | string | | The type of template field. One of: `standard_field`, `custom_field`. | | `fields[].examples` | | | | Example: Response Example ```json { "fields": [ { "data_type": "datetime", "default_value": null, "description": "The time the incident was created.", "domain": { "order": 1, "summary": "Incident" }, "example": "2023-11-22T07:12:50Z", "keyword": null, "summary": "incident.created_at", "type": "standard_field" }, { "data_type": "string", "default_value": null, "description": "The name of the escalation policy attached to the service that the incident is on", "domain": { "order": 1, "summary": "Incident" }, "example": "Another Escalation Policy", "keyword": "name", "summary": "incident.escalation_policy.summary", "type": "standard_field" }, { "data_type": "string", "default_value": "default value", "description": "An account defined custom field", "domain": { "order": 1, "summary": "Incident" }, "example": null, "keyword": null, "summary": "incident.custom_field", "type": "custom_field" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/get-templates # List templates `GET https://api.pagerduty.com/templates` Get a list of all the template on an account Scoped OAuth requires: `templates.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `query` | string | | Template name or description to search. | | `template_type` | string | | Filters templates by type. Default: `status_update`. | | `sort_by` | string | | Used to specify both the field you wish to sort the results on (name/created_at), as well as the direction (asc/desc) of the results. The sort_by field and direction should be separated by a colon. Sort direction defaults to ascending. One of: `name`, `name:asc`, `name:desc`, `created_at`, `created_at:asc`, `created_at:desc`. Default: `created_at:asc`. | ## Response 200 A paginated array of templates. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `templates` | array of object | yes | | | `templates[].template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `templates[].name` | string | | The name of the template. | | `templates[].description` | string \| null | | Description of the template. | | `templates[].templated_fields` | object | | | | `templates[].templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `templates[].templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `templates[].templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | | `templates[].id` | string | | Read-only. | | `templates[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `templates[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `templates[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `templates[].type` | string | | One of: `template`. | | `templates[].created_by` | one of: object \| object | | User/Account object reference of the creator. | | `templates[].created_by.id` | string | yes | (option 1) Read-only. | | `templates[].created_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `templates[].created_by.type` | string | yes | (option 1) One of: `user_reference`. | | `templates[].created_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `templates[].created_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `templates[].created_by.id` | string | yes | (option 2) Read-only. | | `templates[].created_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `templates[].created_by.type` | string | yes | (option 2) One of: `account_reference`. | | `templates[].created_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `templates[].created_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `templates[].updated_by` | one of: object \| object | | User/Account object reference of the updator. | | `templates[].updated_by.id` | string | yes | (option 1) Read-only. | | `templates[].updated_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `templates[].updated_by.type` | string | yes | (option 1) One of: `user_reference`. | | `templates[].updated_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `templates[].updated_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `templates[].updated_by.id` | string | yes | (option 2) Read-only. | | `templates[].updated_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `templates[].updated_by.type` | string | yes | (option 2) One of: `account_reference`. | | `templates[].updated_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `templates[].updated_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "limit": 25, "more": false, "offset": 0, "templates": [ { "created_at": "2022-12-30T16:00:00Z", "created_by": { "id": "PDZR4CN", "self": "https://api.pagerduty.com/users/PDZR4CN", "type": "user_reference" }, "description": "Sample template description", "id": "PBZUP2B", "name": "Sample Template 160", "self": "https://api.pagerduty.com/templates/PBZUP2B", "template_type": "status_update", "type": "template", "updated_at": "2022-12-30T16:00:00Z", "updated_by": { "id": "PGY287N", "self": "https://api.pagerduty.com/users/PGY287N", "type": "user_reference" } } ], "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/render-template # Render a template `POST https://api.pagerduty.com/templates/{id}/render` Render a template. This endpoint has a variable request body depending on the template type. For the `status_update` template type, the caller will provide the incident id, and a status update message. Scoped OAuth requires: `templates.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `incident_id` | string | | (option 1) The incident id to render the template for. | | `status_update` | object | | (option 1) | | `status_update.message` | string | | An optional status update message that will be sent to the template. | | `external` | | | (option 1) An optional object collection that can be referenced in the template. | Example: Request Example ```json { "incident_id": "QT4KHLK034QWE34", "status_update": { "message": "Status update message" } } ``` ## Response 200 Successful operation ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `templated_fields` | object | | | | `templated_fields.email_subject` | string | | The rendered e-mail subject. | | `templated_fields.email_body` | string | | The rendered e-mail body. | | `templated_fields.message` | string | | The rendered short message (SMS, Push, Slack, etc) | | `warnings` | object | | List of render warnings messages for each rendered field. (Ex: ["{{incident.invalid_field}} does not exist."]) | | `warnings.email_subject` | array of string | | List of warnings for email_subject. | | `warnings.email_body` | array of string | | List of warnings for email_body. | | `warnings.message` | array of string | | List of warnings for message field. | | `errors` | array of string | | List of errors. | Example: response ```json { "templated_fields": { "email_subject": "Update: Status update message", "email_body": "
Status update message
", "message": "Update: Status update message" }, "warnings": [ { "email_body": [ "{{incident.bad_value}} does not exist." ] } ], "errors": [] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/templates/update-template # Update a template `PUT https://api.pagerduty.com/templates/{id}` Update an existing template Scoped OAuth requires: `templates.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `template` | object | yes | | | `template.template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `template.name` | string | | The name of the template. | | `template.description` | string \| null | | Description of the template. | | `template.templated_fields` | object | | | | `template.templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `template.templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `template.templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | Example: Request Example ```json { "template": { "description": "Sample template description", "templated_fields": { "email_body": "
sample
", "email_subject": "Sample email Subject", "message": "Sample SMS message" }, "name": "Sample Template", "template_type": "status_update" } } ``` ## Response 200 Successful operation ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `template` | object | yes | | | `template.template_type` | string | | The type of template (`status_update` is the only supported template at this time) One of: `status_update`. | | `template.name` | string | | The name of the template. | | `template.description` | string \| null | | Description of the template. | | `template.templated_fields` | object | | | | `template.templated_fields.email_subject` | string \| null | | The subject of the e-mail. | | `template.templated_fields.email_body` | string \| null | | The HTML body of the e-mail message. | | `template.templated_fields.message` | string \| null | | The short-message of the template (SMS, Push notification, Slack, etc) | | `template.id` | string | | Read-only. | | `template.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `template.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.type` | string | | One of: `template`. | | `template.created_by` | one of: object \| object | | User/Account object reference of the creator. | | `template.created_by.id` | string | yes | (option 1) Read-only. | | `template.created_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.created_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.created_by.id` | string | yes | (option 2) Read-only. | | `template.created_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.created_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.created_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.created_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by` | one of: object \| object | | User/Account object reference of the updator. | | `template.updated_by.id` | string | yes | (option 1) Read-only. | | `template.updated_by.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 1) One of: `user_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `template.updated_by.id` | string | yes | (option 2) Read-only. | | `template.updated_by.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `template.updated_by.type` | string | yes | (option 2) One of: `account_reference`. | | `template.updated_by.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `template.updated_by.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "template": { "created_at": "2022-08-19T13:46:22Z", "created_by": { "id": "PF9KMXH", "self": "https://api.pagerduty.com/users/PF9KMXH", "type": "user_reference" }, "description": "Sample template description", "templated_fields": { "email_body": "
sample
", "email_subject": "Sample email Subject", "message": "Sample SMS message" }, "id": "PCCR863", "name": "Sample Template", "self": "https://api.pagerduty.com/templates/PCCR863", "template_type": "status_update", "type": "template", "updated_at": "2022-08-19T13:46:22Z", "updated_by": { "id": "PF9KMXH", "self": "https://api.pagerduty.com/users/PF9KMXH", "type": "user_reference" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user # Create a user `POST https://api.pagerduty.com/users` Create a new 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | | `From` | string (email) | yes | The email address of a valid user associated with the account making the request. | ## Request body (`application/json`) The user to be created. | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.license` | object | | | | `user.license.id` | string | yes | Read-only. | | `user.license.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.license.type` | string | yes | One of: `license_reference`. | | `user.license.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.license.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "user": { "type": "user", "name": "Earline Greenholt", "email": "125.greenholt.earline@graham.name", "time_zone": "America/Lima", "color": "green", "role": "admin", "job_title": "Director of Engineering", "avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png", "description": "I'm the boss", "license": { "id": "PTDVERC", "type": "license_reference" } } } ``` ## Response 201 The user that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "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" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user-contact-method # Create a user contact method `POST https://api.pagerduty.com/users/{id}/contact_methods` Create a new contact method for the 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The contact method to be created. | Field | Type | Required | Description | |---|---|---|---| | `contact_method` | one of: object \| object \| object \| object | yes | | | `contact_method.id` | string | | (option 1) Read-only. | | `contact_method.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_method.blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 2) Read-only. | | `contact_method.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_method.sounds` | array of object | | (option 2) | | `contact_method.sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_method.sounds[].file` | string | | The sound file name. | | `contact_method.created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_method.blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 3) Read-only. | | `contact_method.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_method.enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | | `contact_method.id` | string | | (option 4) Read-only. | | `contact_method.summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 4) One of: `whatsapp_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 4) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 4) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 4) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 4) If true, this phone is capable of receiving WhatsApp messages. Read-only. | | `contact_method.blacklisted` | boolean | | (option 4) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | Example: Request Example ```json { "contact_method": { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } } ``` ## Response 201 The contact method that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `contact_method` | one of: object \| object \| object | | | | `contact_method.id` | string | | (option 1) Read-only. | | `contact_method.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_method.blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 2) Read-only. | | `contact_method.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_method.sounds` | array of object | | (option 2) | | `contact_method.sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_method.sounds[].file` | string | | The sound file name. | | `contact_method.created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_method.blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 3) Read-only. | | `contact_method.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_method.enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | Example: Response Example ```json { "contact_method": { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user-handoff-notification-rule # Create a User Handoff Notification Rule `POST https://api.pagerduty.com/users/{id}/oncall_handoff_notification_rules` Create a new Handoff Notification Rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The Handoff Notification Rule to be created. | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rule` | object | yes | A rule for contacting the user for Handoff Notifications. | | `oncall_handoff_notification_rule.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.notify_advance_in_minutes` | integer | | The delay before firing the rule, in minutes. Minimum: 0. | | `oncall_handoff_notification_rule.handoff_type` | string | yes | The type of handoff being created. One of: `both`, `oncall`, `offcall`. Default: `both`. | | `oncall_handoff_notification_rule.contact_method` | object | yes | | | `oncall_handoff_notification_rule.contact_method.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncall_handoff_notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `oncall_handoff_notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncall_handoff_notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "oncall_handoff_notification_rule": { "id": "PXPGF43", "handoff_type": "both", "notify_advance_in_minutes": 180, "contact_method": { "id": "PXPGF42", "type": "email_contact_method" } } } ``` ## Response 201 The Handoff Notification Rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rule` | object | yes | A rule for contacting the user for Handoff Notifications. Same fields as `oncall_handoff_notification_rule` above. | Example: Response Example ```json { "oncall_handoff_notification_rule": { "id": "PXPGF42", "handoff_type": "both", "notify_advance_in_minutes": 180, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user-notification-rule # Create a user notification rule `POST https://api.pagerduty.com/users/{id}/notification_rules` Create a new notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The notification rule to be created. | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | yes | | | `notification_rule.id` | string | | Read-only. | | `notification_rule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.type` | string | yes | The type of object being created. One of: `assignment_notification_rule`. Default: `assignment_notification_rule`. | | `notification_rule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.start_delay_in_minutes` | integer | yes | The delay before firing the rule, in minutes. Minimum: 0. | | `notification_rule.contact_method` | object | yes | | | `notification_rule.contact_method.id` | string | yes | Read-only. | | `notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.urgency` | string | yes | Which incident urgency this rule is used for. Account must have the `urgencies` ability to have a low urgency notification rule. One of: `high`, `low`. | Example: Request Example ```json { "notification_rule": { "type": "assignment_notification_rule", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method" }, "urgency": "high" } } ``` ## Response 201 The notification rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | yes | Same fields as `notification_rule` above. | Example: Response Example ```json { "notification_rule": { "id": "PXPGF42", "type": "assignment_notification_rule", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/PPSCXAN", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00", "urgency": "high" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user-notification-subscriptions # Create Notification Subcriptions `POST https://api.pagerduty.com/users/{id}/notification_subscriptions` Create new Notification Subscriptions for the given User. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to subscribe to. | Field | Type | Required | Description | |---|---|---|---| | `subscribables` | array of object | yes | Min items: 1. Items must be unique. | | `subscribables[].subscribable_id` | string | | The ID of the entity to subscribe to. | | `subscribables[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | Example: Request Example ```json { "subscribables": [ { "subscribable_type": "incident", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1235" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `subscriptions` | array of object | | | | `subscriptions[].subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].account_id` | string | | The type of the entity being subscribed to. | | `subscriptions[].result` | string | | The resulting status of the subscription. One of: `success`, `duplicate`, `unauthorized`. | Example: Response Example ```json { "subscriptions": [ { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscriber_id": "PD1234", "subscriber_type": "user", "result": "success" }, { "account_id": "PD1234", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "user", "result": "duplicate" }, { "account_id": "PD1234", "subscribable_id": "PD1235", "subscribable_type": "business_service", "subscriber_id": "PD1234", "subscriber_type": "user", "result": "unauthorized" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/create-user-status-update-notification-rule # Create a user status update notification rule `POST https://api.pagerduty.com/users/{id}/status_update_notification_rules` Create a new status update notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The status update notification rule to be created. | Field | Type | Required | Description | |---|---|---|---| | `status_update_notification_rule` | object | yes | A rule for contacting the user for Incident Status Updates. | | `status_update_notification_rule.contact_method` | object | yes | | | `status_update_notification_rule.contact_method.id` | string | yes | Read-only. | | `status_update_notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `status_update_notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `status_update_notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `status_update_notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "status_update_notification_rule": { "contact_method": { "id": "PXPGF42", "type": "email_contact_method" } } } ``` ## Response 201 The status update notification rule that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status_update_notification_rule` | object | yes | A rule for contacting the user for Incident Status Updates. Same fields as `status_update_notification_rule` above. | Example: Response Example ```json { "status_update_notification_rule": { "id": "PXPGF42", "type": "status_update_notification_rule", "summary": "contact method PXPGF42 used as status_update_notification_rule", "self": "https://api.pagerduty.com/users/PXPGF42/status_update_notification_rules/PPSCXAN", "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user # Delete a user `DELETE https://api.pagerduty.com/users/{id}` Remove an existing user. Returns 400 if the user has assigned incidents unless your [pricing plan](https://www.pagerduty.com/pricing) has the `offboarding` feature and the account is [configured](https://support.pagerduty.com/docs/offboarding#section-additional-configurations) appropriately. Note that the incidents reassignment process is asynchronous and has no guarantee to complete before the api call return. [*Learn more about `offboarding` feature*](https://support.pagerduty.com/docs/offboarding). 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The user was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-contact-method # Delete a user's contact method `DELETE https://api.pagerduty.com/users/{id}/contact_methods/{contact_method_id}` Remove a user's contact method. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `contact_method_id` | string | yes | The contact method ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The contact method was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-handoff-notification-rule # Delete a User's Handoff Notification rule `DELETE https://api.pagerduty.com/users/{id}/oncall_handoff_notification_rules/{oncall_handoff_notification_rule_id}` Remove a User's Handoff Notification Rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `oncall_handoff_notification_rule_id` | string | yes | The oncall handoff notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The handoff notification rule was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-notification-rule # Delete a user's notification rule `DELETE https://api.pagerduty.com/users/{id}/notification_rules/{notification_rule_id}` Remove a user's notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `notification_rule_id` | string | yes | The notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The notification rule was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-session # Delete a user's session `DELETE https://api.pagerduty.com/users/{id}/sessions/{type}/{session_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated as OAuth token revocation is now synchronous. Please use the [DELETE /oauth_delegations endpoint](https://docs.pagerduty.com/developer/api/reference/rest/oauth-delegations/delete-oauth-delegations) instead. Delete a user's session. Beginning November 2021, user sessions no longer includes newly issued OAuth tokens. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:sessions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `type` | string | yes | The session type for the user session ID. | | `session_id` | string | yes | The session ID for the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The user session was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-sessions # Delete all user sessions `DELETE https://api.pagerduty.com/users/{id}/sessions` **Deprecated.** > ### Deprecated > This endpoint is deprecated as OAuth token revocation is now synchronous. Please use the [DELETE /oauth_delegations endpoint](https://docs.pagerduty.com/developer/api/reference/rest/oauth-delegations/delete-oauth-delegations) instead. Delete all user sessions. Beginning November 2021, user sessions no longer includes newly issued OAuth tokens. If you are interested in deleting mobile app sessions, refer to the Delete OAuth Delegations endpoint. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:sessions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The user sessions were all deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/delete-user-status-update-notification-rule # Delete a user's status update notification rule `DELETE https://api.pagerduty.com/users/{id}/status_update_notification_rules/{status_update_notification_rule_id}` Remove a user's status update notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `status_update_notification_rule_id` | string | yes | The status update notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The status update notification rule was deleted successfully. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-current-user # Get the current user `GET https://api.pagerduty.com/users/me` 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](https://docs.pagerduty.com/developer/api-concepts#users) ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. Use `calendar_urls` to include `http_cal_url` and `web_cal_url`; account admins with `can_update_user` may use this to retrieve another user's calendar feed URLs. Note that these URLs are bearer credentials: anyone with the URL can read that user's on-call calendar. One of: `contact_methods`, `notification_rules`, `teams`, `subdomains`, `calendar_urls`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The requesting user. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "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" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user # Get a user `GET https://api.pagerduty.com/users/{id}` 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional Models to include in response. Use `calendar_urls` to include `http_cal_url` and `web_cal_url`; account admins with `can_update_user` may use this to retrieve another user's calendar feed URLs. Note that these URLs are bearer credentials: anyone with the URL can read that user's on-call calendar. One of: `contact_methods`, `notification_rules`, `teams`, `subdomains`, `calendar_urls`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "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" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-contact-method # Get a user's contact method `GET https://api.pagerduty.com/users/{id}/contact_methods/{contact_method_id}` Get details about a User's contact method. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `contact_method_id` | string | yes | The contact method ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's contact method requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `contact_method` | one of: object \| object \| object | | | | `contact_method.id` | string | | (option 1) Read-only. | | `contact_method.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_method.blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 2) Read-only. | | `contact_method.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_method.sounds` | array of object | | (option 2) | | `contact_method.sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_method.sounds[].file` | string | | The sound file name. | | `contact_method.created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_method.blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 3) Read-only. | | `contact_method.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_method.enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | Example: Response Example ```json { "contact_method": { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-contact-methods # List a user's contact methods `GET https://api.pagerduty.com/users/{id}/contact_methods` List contact methods of your PagerDuty 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of contact methods. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `contact_methods` | array of one of: object \| object \| object \| object | | | | `contact_methods[].id` | string | | (option 1) Read-only. | | `contact_methods[].summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_methods[].type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_methods[].self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_methods[].html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_methods[].label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_methods[].address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_methods[].country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_methods[].enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_methods[].blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_methods[].id` | string | | (option 2) Read-only. | | `contact_methods[].summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_methods[].type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_methods[].self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_methods[].html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_methods[].label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_methods[].address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_methods[].device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_methods[].sounds` | array of object | | (option 2) | | `contact_methods[].sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_methods[].sounds[].file` | string | | The sound file name. | | `contact_methods[].created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_methods[].blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_methods[].id` | string | | (option 3) Read-only. | | `contact_methods[].summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_methods[].type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_methods[].self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_methods[].html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_methods[].label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_methods[].address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_methods[].send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_methods[].enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | | `contact_methods[].id` | string | | (option 4) Read-only. | | `contact_methods[].summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_methods[].type` | string | yes | (option 4) One of: `whatsapp_contact_method`. | | `contact_methods[].self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `contact_methods[].html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_methods[].label` | string | yes | (option 4) The label (e.g., "Work", "Mobile", etc.). | | `contact_methods[].address` | string | yes | (option 4) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_methods[].country_code` | integer | yes | (option 4) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_methods[].enabled` | boolean | | (option 4) If true, this phone is capable of receiving WhatsApp messages. Read-only. | | `contact_methods[].blacklisted` | boolean | | (option 4) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | Example: Response Example ```json { "contact_methods": [ { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-delegation # Get a user's delegation `GET https://api.pagerduty.com/users/{id}/oauth_delegations/{delegation_id}` Get details about a specific OAuth delegation. This endpoint replaces the deprecated `/users/{id}/sessions/{session_id}` endpoint. **Required OAuth Scope:** For Scoped OAuth requests, this operation requires the `oauth_delegations.read` scope. Scoped OAuth requires: `oauth_delegations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `delegation_id` | string | yes | The ID of the delegation. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Delegation retrieved successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The unique identifier for the delegation. | | `status` | string | yes | The current status of the delegation. One of: `issued`, `revoked`. | | `client_id` | string | yes | The OAuth client ID. | | `delegation_type` | string | yes | The type of delegation. One of: `web`, `mobile`, `integration`. | | `scope` | string | yes | The OAuth scopes granted. | | `created_at` | string (date-time) | yes | When the delegation was created (ISO 8601 format) | | `expires_at` | string (date-time) | yes | When the delegation expires (ISO 8601 format) | | `self` | string (uri) | yes | URL to retrieve this delegation in detail. | Example: Response Example ```json { "oauth_delegation": { "client_id": "PagerDutyLogin", "created_at": "2026-01-01T12:00:00Z", "expires_at": "2026-01-08T12:00:00Z", "id": "e53326c6-a713-409c-8f7e-ps1xczid", "scope": "openid profile", "self": "https://api.pagerduty.com/users/PXPGF42/oauth_delegations/e53326c6-a713-409c-8f7e-ps1xczid", "status": "issued", "type": "web" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-handoff-notifiaction-rule # Get a user's handoff notification rule `GET https://api.pagerduty.com/users/{id}/oncall_handoff_notification_rules/{oncall_handoff_notification_rule_id}` Get details about a User's Handoff Notification Rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `oncall_handoff_notification_rule_id` | string | yes | The oncall handoff notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's handoff notification rule requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rule` | object | yes | A rule for contacting the user for Handoff Notifications. | | `oncall_handoff_notification_rule.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.notify_advance_in_minutes` | integer | | The delay before firing the rule, in minutes. Minimum: 0. | | `oncall_handoff_notification_rule.handoff_type` | string | yes | The type of handoff being created. One of: `both`, `oncall`, `offcall`. Default: `both`. | | `oncall_handoff_notification_rule.contact_method` | object | yes | | | `oncall_handoff_notification_rule.contact_method.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncall_handoff_notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `oncall_handoff_notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncall_handoff_notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "oncall_handoff_notification_rule": { "id": "PXPGF42", "handoff_type": "both", "notify_advance_in_minutes": 60, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-handoff-notification-rules # List a User's Handoff Notification Rules `GET https://api.pagerduty.com/users/{id}/oncall_handoff_notification_rules` List Handoff Notification Rules of your PagerDuty 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of Handoff Notification Rules. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rules` | array of object | yes | | | `oncall_handoff_notification_rules[].id` | string | yes | Read-only. | | `oncall_handoff_notification_rules[].notify_advance_in_minutes` | integer | | The delay before firing the rule, in minutes. Minimum: 0. | | `oncall_handoff_notification_rules[].handoff_type` | string | yes | The type of handoff being created. One of: `both`, `oncall`, `offcall`. Default: `both`. | | `oncall_handoff_notification_rules[].contact_method` | object | yes | | | `oncall_handoff_notification_rules[].contact_method.id` | string | yes | Read-only. | | `oncall_handoff_notification_rules[].contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncall_handoff_notification_rules[].contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `oncall_handoff_notification_rules[].contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncall_handoff_notification_rules[].contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "oncall_handoff_notification_rules": [ { "id": "PXPGF42", "handoff_type": "both", "notify_advance_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-license # Get the License allocated to a User `GET https://api.pagerduty.com/users/{id}/license` Get the License allocated to a User Scoped OAuth requires: `licenses.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The License allocated to the User ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `license` | object | yes | | | `license.id` | string | yes | Uniquely identifies the resource. | | `license.description` | string | yes | Description of the License. May include the names of add-ons associated with the License, if there are any. | | `license.name` | string | yes | Name of the License. | | `license.valid_roles` | array of string | yes | The roles a User with this License can have. | | `license.role_group` | string | | Indicates whether this License is assignable to full or stakeholder Users. One of: `FullUser`, `Stakeholder`. | | `license.type` | string | | Type of object. | | `license.self` | string | | API URL to access the License. | | `license.html_url` | string | | HTML URL to access the License. | | `license.summary` | string | | Summary of the License. | Example: Response Example ```json { "license": { "id": "PIP248G", "name": "Business (Full User)", "description": "Event Intelligence", "valid_roles": [ "owner", "admin", "user", "limited_user", "observer", "restricted_access" ], "role_group": "FullUser", "summary": "Business (Full User)", "type": "license", "self": null, "html_url": null } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-notification-rule # Get a user's notification rule `GET https://api.pagerduty.com/users/{id}/notification_rules/{notification_rule_id}` Get details about a user's notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `notification_rule_id` | string | yes | The notification rule ID on the user. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `contact_methods`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's notification rule requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | yes | | | `notification_rule.id` | string | | Read-only. | | `notification_rule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.type` | string | yes | The type of object being created. One of: `assignment_notification_rule`. Default: `assignment_notification_rule`. | | `notification_rule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.start_delay_in_minutes` | integer | yes | The delay before firing the rule, in minutes. Minimum: 0. | | `notification_rule.contact_method` | object | yes | | | `notification_rule.contact_method.id` | string | yes | Read-only. | | `notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.urgency` | string | yes | Which incident urgency this rule is used for. Account must have the `urgencies` ability to have a low urgency notification rule. One of: `high`, `low`. | Example: Response Example ```json { "notification_rule": { "id": "PXPGF42", "type": "assignment_notification_rule", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/PPSCXAN", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" }, "created_at": "2016-02-01T16:06:27-05:00", "urgency": "high" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-notification-rules # List a user's notification rules `GET https://api.pagerduty.com/users/{id}/notification_rules` List notification rules of your PagerDuty 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `contact_methods`. Items must be unique. | | `urgency` | string | | The incident urgency for which the notification rules are applied. If not specified, defaults to `high`. One of: `high`, `low`, `all`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of notification rules. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rules` | array of object | yes | | | `notification_rules[].id` | string | | Read-only. | | `notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rules[].type` | string | yes | The type of object being created. One of: `assignment_notification_rule`. Default: `assignment_notification_rule`. | | `notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rules[].start_delay_in_minutes` | integer | yes | The delay before firing the rule, in minutes. Minimum: 0. | | `notification_rules[].contact_method` | object | yes | | | `notification_rules[].contact_method.id` | string | yes | Read-only. | | `notification_rules[].contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rules[].contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `notification_rules[].contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rules[].contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rules[].urgency` | string | yes | Which incident urgency this rule is used for. Account must have the `urgencies` ability to have a low urgency notification rule. One of: `high`, `low`. | Example: Response Example ```json { "notification_rules": [ { "id": "PXPGF42", "type": "assignment_notification_rule", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/PPSCXAN", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00", "urgency": "high" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-notification-subscriptions # List Notification Subscriptions `GET https://api.pagerduty.com/users/{id}/notification_subscriptions` Retrieve a list of Notification Subscriptions the given User has. > Users must be added through `POST /users/{id}/notification_subscriptions` to be returned from this endpoint. Scoped OAuth requires: `subscribers.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `subscriptions` | array of object | yes | | | `subscriptions[].subscription` | object | | An object describing the relationship of a NotificationSubscriber and a NotificationSubscribable. | | `subscriptions[].subscription.subscriber_id` | string | | The ID of the entity being subscribed. | | `subscriptions[].subscription.subscriber_type` | string | | The type of the entity being subscribed. One of: `user`, `team`. | | `subscriptions[].subscription.subscribable_id` | string | | The ID of the entity being subscribed to. | | `subscriptions[].subscription.subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | | `subscriptions[].subscription.account_id` | string | | The ID of the account belonging to the subscriber entity. | | `subscriptions[].subscribable_name` | string \| null | | The name of the subscribable. | Example: Response Example ```json { "subscriptions": [ { "subscription": { "subscriber_id": "PD1234", "subscriber_type": "user", "subscribable_id": "PD1234", "subscribable_type": "incident", "subscribable_name": null, "account_id": "PD1234" } }, { "subscription": { "subscriber_id": "PD1234", "subscriber_type": "user", "subscribable_id": "PD1234", "subscribable_type": "business_service", "subscribable_name": "business service name", "account_id": "PD1234" } } ], "limit": 2, "offset": 0, "total": 1000, "more": true } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-session # Get a user's session `GET https://api.pagerduty.com/users/{id}/sessions/{type}/{session_id}` **Deprecated.** > ### Deprecated > This endpoint is deprecated, please use the [Get OAuth Delegation endpoint](https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-delegation) instead. Get details about a user's session. Beginning November 2021, user sessions no longer includes newly issued OAuth tokens. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:sessions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `type` | string | yes | The session type for the user session ID. | | `session_id` | string | yes | The session ID for the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's session requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user_session` | object | yes | | | `user_session.id` | string | yes | Read-only. | | `user_session.user_id` | string | yes | Read-only. | | `user_session.created_at` | string (date-time) | yes | The date/time the user session was first created. Read-only. | | `user_session.type` | string | yes | The type of the session. Read-only. One of: `browser`, `oauth`. | | `user_session.summary` | string | yes | The summary of the session. Read-only. | Example: Response Example ```json { "user_session": { "id": "PXPGF42", "user_id": "PXPGF42", "created_at": "2018-10-06T21:30:42Z", "summary": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36", "type": "browser" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-sessions # List a user's active sessions `GET https://api.pagerduty.com/users/{id}/sessions` **Deprecated.** > ### Deprecated > This endpoint is deprecated, please use the [List OAuth Delegations endpoint](https://docs.pagerduty.com/developer/api/reference/rest/users/list-user-delegations) instead. List active sessions of a PagerDuty user. Beginning November 2021, active sessions no longer includes newly issued OAuth tokens. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:sessions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of the user's active sessions. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user_sessions` | array of object | yes | | | `user_sessions[].id` | string | yes | Read-only. | | `user_sessions[].user_id` | string | yes | Read-only. | | `user_sessions[].created_at` | string (date-time) | yes | The date/time the user session was first created. Read-only. | | `user_sessions[].type` | string | yes | The type of the session. Read-only. One of: `browser`, `oauth`. | | `user_sessions[].summary` | string | yes | The summary of the session. Read-only. | Example: Response Example ```json { "user_sessions": [ { "id": "PXPGF42", "user_id": "PXPGF42", "created_at": "2018-10-06T21:30:42Z", "summary": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36", "type": "browser" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-status-update-notification-rule # Get a user's status update notification rule `GET https://api.pagerduty.com/users/{id}/status_update_notification_rules/{status_update_notification_rule_id}` Get details about a user's status update notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `status_update_notification_rule_id` | string | yes | The status update notification rule ID on the user. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `contact_methods`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's status update notification rule requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | yes | A rule for contacting the user for Incident Status Updates. | | `notification_rule.contact_method` | object | yes | | | `notification_rule.contact_method.id` | string | yes | Read-only. | | `notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "notification_rule": { "id": "PXPGF42", "type": "status_update_notification_rule", "summary": "contact method PXPGF42 used as status_update_notification_rule", "self": "https://api.pagerduty.com/users/PXPGF42/status_update_notification_rules/PPSCXAN", "contact_method": { "id": "PTDVERC", "type": "email_contact_method_reference", "summary": "Default", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PTDVERC", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/get-user-status-update-notification-rules # List a user's status update notification rules `GET https://api.pagerduty.com/users/{id}/status_update_notification_rules` List status update notification rules of your PagerDuty 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `include[]` | string | | Array of additional details to include. One of: `contact_methods`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of status update notification rules. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `status_update_notification_rules` | array of object | yes | | | `status_update_notification_rules[].contact_method` | object | yes | | | `status_update_notification_rules[].contact_method.id` | string | yes | Read-only. | | `status_update_notification_rules[].contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `status_update_notification_rules[].contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `status_update_notification_rules[].contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `status_update_notification_rules[].contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Response Example ```json { "status_update_notification_rules": [ { "id": "PXPGF42", "type": "status_update_notification_rule", "summary": "contact method PXPGF42 used as status_update_notification_rule", "self": "https://api.pagerduty.com/users/PXPGF42/status_update_notification_rules/PPSCXAN", "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/list-user-delegations # List a user's delegations `GET https://api.pagerduty.com/users/{id}/oauth_delegations` Get a list of OAuth delegations for a specific user. This endpoint replaces the deprecated `/users/{id}/sessions` endpoint. **Required OAuth Scope:** For Scoped OAuth requests, this operation requires the `oauth_delegations.read` scope. Scoped OAuth requires: `oauth_delegations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `delegation_type` | string | | The type of OAuth delegations to filter on. Allowed values are 'mobile', 'web', and 'integration'. You can pass one or more types in, separated by commas (e.g., `type=web,mobile`). One of: `mobile`, `web`, `integration`. | | `status` | string | | The status of the delegations to return. Allowed values are 'issued' and 'revoked'. You can pass one or more statuses in, separated by commas (e.g., `status=issued,revoked`). One of: `issued`, `revoked`. | | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Delegations retrieved sucessfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oauth_delegations` | array of object | yes | Array of OAuth delegation objects. | | `oauth_delegations[].id` | string | yes | The unique identifier for the delegation. | | `oauth_delegations[].status` | string | yes | The current status of the delegation. One of: `issued`, `revoked`. | | `oauth_delegations[].client_id` | string | yes | The OAuth client ID. | | `oauth_delegations[].delegation_type` | string | yes | The type of delegation. One of: `web`, `mobile`, `integration`. | | `oauth_delegations[].scope` | string | yes | The OAuth scopes granted. | | `oauth_delegations[].created_at` | string (date-time) | yes | When the delegation was created (ISO 8601 format) | | `oauth_delegations[].expires_at` | string (date-time) | yes | When the delegation expires (ISO 8601 format) | | `oauth_delegations[].self` | string (uri) | yes | URL to retrieve this delegation in detail. | | `limit` | integer | yes | Number of results per page. | | `more` | boolean | yes | Whether there are more results available. | | `next_cursor` | string | | Cursor for retrieving the next page (only present when more is true) | Example: Response Example ```json { "oauth_delegations": [ { "id": "e53326c6-a713-409c-8f7e-ps1xczid", "type": "web", "client_id": "PagerDutyLogin", "self": "https://api.pagerduty.com/users/PXPGF42/oauth_delegations/e53326c6-a713-409c-8f7e-ps1xczid", "created_at": "2026-01-01T12:00:00Z", "expires_at": "2026-01-08T12:00:00Z", "status": "issued", "scope": "openid profile" } ], "limit": 25, "more": false, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/list-users # List users `GET https://api.pagerduty.com/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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `query` | string | | Filters the result, showing only the records whose name matches the query. | | `team_ids[]` | array of string | | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. | | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `include[]` | string | | Array of additional Models to include in response. One of: `contact_methods`, `notification_rules`, `teams`, `subdomains`. Items must be unique. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of users. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `users` | array of object | yes | | | `users[].id` | string | | Read-only. | | `users[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `users[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].name` | string | yes | The name of the user. Max length: 100. | | `users[].email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `users[].time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `users[].color` | string | | The schedule color. | | `users[].role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `users[].avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `users[].description` | string \| null | | The user's bio. | | `users[].invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `users[].job_title` | string | | The user's title. Max length: 100. | | `users[].created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `users[].teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `users[].teams[].id` | string | yes | Read-only. | | `users[].teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].teams[].type` | string | yes | One of: `team_reference`. | | `users[].teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `users[].contact_methods[].id` | string | yes | Read-only. | | `users[].contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `users[].contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `users[].notification_rules[].id` | string | yes | Read-only. | | `users[].notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `users[].notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `users[].notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `users[].notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `users[].http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `users[].web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "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 } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/list-users-audit-records # List audit records for a user `GET https://api.pagerduty.com/users/{id}/audit/records` The response will include audit records with changes that are made to the identified user not changes made by the identified user. The returned records are sorted by the `execution_time` from newest to oldest. See [`Cursor-based pagination`](https://docs.pagerduty.com/developer/pagination) for instructions on how to paginate through the result set. For more information see the [Audit API Document](https://docs.pagerduty.com/developer/audit-records-api). Scoped OAuth requires: `audit_records.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `since` | string (date-time) | | The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours) | | `until` | string (date-time) | | The end of the date range over which you want to search. If not specified, defaults to `now()`. May not be more than 31 days after `since`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 Records matching the query criteria. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `records` | array of object | yes | | | `records[].id` | string | yes | | | `records[].self` | string \| null | | Record URL. | | `records[].execution_time` | string (date-time) | yes | The date/time the action executed, in ISO8601 format and millisecond precision. | | `records[].execution_context` | object \| null | | Action execution context. | | `records[].execution_context.request_id` | string \| null | | Request Id. | | `records[].execution_context.remote_address` | string \| null | | remote address. | | `records[].actors` | array \| null | | | | `records[].method` | object | yes | The method information. | | `records[].method.description` | string \| null | | | | `records[].method.truncated_token` | string \| null | | Truncated token containing the last 4 chars of the token's actual value. | | `records[].method.type` | string | yes | Describes the method used to perform the action: `browser` -- authenticated user session. Session value is not returned in the `truncated_token` field. `oauth` -- access token obtained via the OAuth flow. Truncated token value is returned in the `truncated_token` field. `api_token` -- Pagerduty API token. Truncated token value is returned in the `truncated_token` field. `identity_provider` -- action performed by an Identity provider on behalf of a user. No value is returned in the `truncated_token` field. `other` -- Method that does not fall in the predefined categories. Truncated token value MAY be returned in the `truncated_token` field. One of: `browser`, `oauth`, `api_token`, `identity_provider`, `other`. | | `records[].root_resource` | object | yes | | | `records[].root_resource.id` | string | yes | Read-only. | | `records[].root_resource.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `records[].root_resource.type` | string | yes | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `records[].root_resource.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `records[].root_resource.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `records[].action` | string | yes | | | `records[].details` | object \| null | | Additional details to provide further information about the action or the resource that has been audited. | | `records[].details.resource` | object | yes | Same fields as `records[].root_resource` above. | | `records[].details.fields` | array \| null | | A set of fields that have been affected. The fields that have not been affected MAY be returned. | | `records[].details.references` | array \| null | | A set of references that have been affected. | | `response_metadata` | one of: object | | | | `response_metadata.messages` | array \| null | | (option 1) | | `limit` | integer | yes | The minimum of the `limit` parameter used in the request or the maximum request size of the API. Read-only. | | `next_cursor` | string \| null | yes | An opaque string than will deliver the next set of results when provided as the `cursor` parameter in a subsequent request. A `null` value for this field indicates that there are no additional results. Read-only. | Example: Response Example ```json { "records": [ { "id": "PD_ADD_HIGH_URGENCY_NOTIFICATION", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_NOTIFICATION_RULE_HIGH", "summary": "High Urgency (Email: Default)", "type": "assignment_notification_rule_reference" } ], "name": "notification_rules" } ], "resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.343Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_ADD_HIGH_URGENCY_EMAIL_CONTACT", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "start_delay_in_minutes", "value": "0" }, { "name": "urgency", "value": "high" } ], "references": [ { "added": [ { "id": "PD_CONTACT_METHOD", "summary": "Default", "type": "email_contact_method_reference" } ], "name": "contact_method" } ], "resource": { "id": "PD_NOTIFICATION_RULE_HIGH", "summary": "High Urgency (Email: Default)", "type": "assignment_notification_rule_reference" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.343Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_ADD_LOW_URGENCY_EMAIL_RULE", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "start_delay_in_minutes", "value": "0" }, { "name": "urgency", "value": "low" } ], "references": [ { "added": [ { "id": "PD_CONTACT_METHOD", "summary": "Default", "type": "email_contact_method_reference" } ], "name": "contact_method" } ], "resource": { "id": "PD_NOTIFICATION_RULE_LOW", "summary": "Low Urgency (Email: Default)", "type": "assignment_notification_rule_reference" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.335Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_ADD_LOW_URGENCY_EMAIL_CONTACT", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_NOTIFICATION_RULE_LOW", "summary": "Low Urgency (Email: Default)", "type": "assignment_notification_rule_reference" } ], "name": "notification_rules" } ], "resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.335Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_EMAIL_CONTACT_FOR_USER", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "label", "value": "Default" }, { "name": "type", "value": "email_contact_method" }, { "name": "address", "value": "testuser@testabc123.com" } ], "resource": { "id": "PD_CONTACT_METHOD", "summary": "Default", "type": "email_contact_method_reference" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.327Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_ADD_EMAIL_CONTACT_TO_USER", "action": "update", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "references": [ { "added": [ { "id": "PD_CONTACT_METHOD", "summary": "Default", "type": "email_contact_method_reference" } ], "name": "contact_methods" } ], "resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:32.327Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, { "id": "PD_CREATE_USER", "action": "create", "actors": [ { "id": "PDUSER", "summary": "John Snow", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER123", "html_url": "https://mydomain.pagerduty.com/users/PD_USER123" } ], "details": { "fields": [ { "name": "name", "value": "Test User" }, { "name": "role", "value": "user" }, { "name": "email", "value": "testuser@testabc123.com" }, { "name": "time_zone", "value": "America/New_York" }, { "name": "description", "value": null }, { "name": "job_title", "value": null }, { "name": "color", "value": "brown" } ], "resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } }, "execution_context": { "request_id": "a68929b2-d0f4-4def-b1d2-6bb744c44e3d" }, "execution_time": "2021-01-05T15:17:31.708Z", "method": { "type": "browser" }, "root_resource": { "id": "PD_USER_999", "summary": "Test User", "type": "user_reference", "self": "https://api.pagerduty.com/users/PD_USER_999", "html_url": "https://mydomain.pagerduty.com/users/PD_USER_999" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 500 Internal Server Error the PagerDuty server experienced an error. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/regenerate-user-private-url-key # Regenerate a user's calendar feed URL key `POST https://api.pagerduty.com/users/{id}/regenerate_private_url_key` Regenerate the private URL key used to construct a user's personal iCal calendar feed URLs (`http_cal_url` and `web_cal_url`). The old key is immediately invalidated; callers should update any stored feed subscriptions with the new key. A user may only regenerate their own key. Account admins may regenerate on behalf of any user. The calendar feed URLs act as bearer credentials: anyone with the URL can read that user's on-call calendar without further authentication. Rotate the key here whenever a URL may have been exposed (for example, if it was shared outside the intended audience or if an admin with `can_update_user` retrieved it via `GET /users/{id}?include[]=calendar_urls`). 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The user's new private URL key. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `private_url_key` | string | yes | The newly generated private URL key for calendar feed URLs. | Example: Response Example ```json { "private_url_key": "ABCDEFGHIJKLMNOP" } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/unsubscribe-user-notification-subscriptions # Remove Notification Subscriptions `POST https://api.pagerduty.com/users/{id}/notification_subscriptions/unsubscribe` Unsubscribe the given User from Notifications on the matching Subscribable entities. Scoped OAuth requires: `subscribers.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The entities to unsubscribe from. | Field | Type | Required | Description | |---|---|---|---| | `subscribables` | array of object | yes | Min items: 1. Items must be unique. | | `subscribables[].subscribable_id` | string | | The ID of the entity to subscribe to. | | `subscribables[].subscribable_type` | string | | The type of the entity being subscribed to. One of: `incident`, `business_service`. | Example: Response Example ```json { "subscribables": [ { "subscribable_type": "incident", "subscribable_id": "PD1234" }, { "subscribable_type": "business_service", "subscribable_id": "PD1234" } ] } ``` ## Response 200 OK ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `deleted_count` | number | yes | | | `unauthorized_count` | number | yes | | | `non_existent_count` | number | yes | | Example: Response Example ```json { "deleted_count": 1, "unauthorized_count": 1, "non_existent_count": 0 } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 422 Unprocessable Entity. Some arguments failed validation checks. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/update-user # Update a user `PUT https://api.pagerduty.com/users/{id}` Update 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The user to be updated. | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.license` | object | | | | `user.license.id` | string | yes | Read-only. | | `user.license.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.license.type` | string | yes | One of: `license_reference`. | | `user.license.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.license.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "user": { "type": "user", "name": "Earline Greenholt", "email": "125.greenholt.earline@graham.name", "time_zone": "America/Lima", "color": "green", "role": "admin", "job_title": "Director of Engineering", "avatar_url": "https://pd-static-assets.pagerduty.com/users/blank-avatar.png", "description": "I'm the boss", "license": { "id": "PTDVERC", "type": "license_reference" } } } ``` ## Response 200 The user that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `user` | object | yes | | | `user.id` | string | | Read-only. | | `user.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.type` | string | yes | The type of object being created. One of: `user`. Default: `user`. | | `user.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.name` | string | yes | The name of the user. Max length: 100. | | `user.email` | string (email) | yes | The user's email address. Min length: 6. Max length: 100. | | `user.time_zone` | string (tzinfo) | | The preferred time zone name. If null, the account's time zone will be used. | | `user.color` | string | | The schedule color. | | `user.role` | string | | The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`. One of: `admin`, `limited_user`, `observer`, `owner`, `read_only_user`, `restricted_access`, `read_only_limited_user`, `user`. | | `user.avatar_url` | string (url) | | The URL of the user's avatar. Read-only. | | `user.description` | string \| null | | The user's bio. | | `user.invitation_sent` | boolean | | If true, the user has an outstanding invitation. Read-only. | | `user.job_title` | string | | The user's title. Max length: 100. | | `user.created_via_sso` | boolean | | If true, the user was created via Single Sign-On (SSO). Read-only. | | `user.teams` | array of object | | The list of teams to which the user belongs. Account must have the `teams` ability to set this. Read-only. | | `user.teams[].id` | string | yes | Read-only. | | `user.teams[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.teams[].type` | string | yes | One of: `team_reference`. | | `user.teams[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.teams[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.contact_methods` | array of object | | The list of contact methods for the user. Read-only. | | `user.contact_methods[].id` | string | yes | Read-only. | | `user.contact_methods[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.contact_methods[].type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `user.contact_methods[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.contact_methods[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.notification_rules` | array of object | | The list of notification rules for the user. Read-only. | | `user.notification_rules[].id` | string | yes | Read-only. | | `user.notification_rules[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `user.notification_rules[].type` | string | yes | One of: `assignment_notification_rule_reference`. | | `user.notification_rules[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `user.notification_rules[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `user.http_cal_url` | string (uri) | | iCal HTTP feed URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | | `user.web_cal_url` | string (uri) | | iCal webcal URL for this user's on-call shifts. Only returned on the `GET /users/{id}` detail endpoint: automatically when viewing your own profile with a user-level token, or when an account admin with `can_update_user` passes `include[]=calendar_urls` for another user. Not returned on list endpoints or with account-level read-only keys. **Security:** this URL is a bearer credential. Anyone with the URL can read the user's on-call calendar without further authentication. Rotate via `POST /users/{id}/regenerate_private_url_key` if it may have been exposed. Read-only. | Example: Response Example ```json { "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" } ] } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/update-user-contact-method # Update a user's contact method `PUT https://api.pagerduty.com/users/{id}/contact_methods/{contact_method_id}` Update a User's contact method. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `contact_method_id` | string | yes | The contact method ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The user's contact method to be updated. | Field | Type | Required | Description | |---|---|---|---| | `contact_method` | one of: object \| object \| object \| object | yes | | | `contact_method.id` | string | | (option 1) Read-only. | | `contact_method.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_method.blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 2) Read-only. | | `contact_method.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_method.sounds` | array of object | | (option 2) | | `contact_method.sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_method.sounds[].file` | string | | The sound file name. | | `contact_method.created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_method.blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 3) Read-only. | | `contact_method.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_method.enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | | `contact_method.id` | string | | (option 4) Read-only. | | `contact_method.summary` | string \| null | | (option 4) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 4) One of: `whatsapp_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 4) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 4) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 4) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 4) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 4) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 4) If true, this phone is capable of receiving WhatsApp messages. Read-only. | | `contact_method.blacklisted` | boolean | | (option 4) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | Example: Request Example ```json { "contact_method": { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } } ``` ## Response 200 The user's contact method that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `contact_method` | one of: object \| object \| object | | | | `contact_method.id` | string | | (option 1) Read-only. | | `contact_method.summary` | string \| null | | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 1) One of: `phone_contact_method`, `sms_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 1) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 1) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 1) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.country_code` | integer | yes | (option 1) The 1-to-3 digit country calling code. Minimum: 1. Maximum: 1999. | | `contact_method.enabled` | boolean | | (option 1) If true, this phone is capable of receiving notifications. Read-only. | | `contact_method.blacklisted` | boolean | | (option 1) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 2) Read-only. | | `contact_method.summary` | string \| null | | (option 2) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 2) One of: `push_notification_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 2) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 2) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 2) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 2) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.device_type` | string | yes | (option 2) The type of device. Read-only. One of: `android`, `ios`. | | `contact_method.sounds` | array of object | | (option 2) | | `contact_method.sounds[].type` | string | | The type of sound. One of: `alert_high_urgency`, `alert_low_urgency`. | | `contact_method.sounds[].file` | string | | The sound file name. | | `contact_method.created_at` | string (date-time) | | (option 2) Time at which the contact method was created. | | `contact_method.blacklisted` | boolean | | (option 2) If true, this phone has been blacklisted by PagerDuty and no messages will be sent to it. Read-only. | | `contact_method.id` | string | | (option 3) Read-only. | | `contact_method.summary` | string \| null | | (option 3) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `contact_method.type` | string | yes | (option 3) One of: `email_contact_method`. | | `contact_method.self` | string \| null (url) | | (option 3) the API show URL at which the object is accessible. Read-only. | | `contact_method.html_url` | string \| null (url) | | (option 3) a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `contact_method.label` | string | yes | (option 3) The label (e.g., "Work", "Mobile", etc.). | | `contact_method.address` | string | yes | (option 3) The "address" to deliver to: email, phone number, etc., depending on the type. | | `contact_method.send_short_email` | boolean | | (option 3) Send an abbreviated email message instead of the standard email output. Useful for email-to-SMS gateways and email based pagers. Default: `false`. | | `contact_method.enabled` | boolean | | (option 3) If true, this email address is capable of receiving email notifications. Read-only. | Example: Response Example ```json { "contact_method": { "id": "PXPGF42", "type": "email_contact_method", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_method/PXPGF42", "label": "Work", "address": "grady.haylie.126@hickle.net", "send_short_email": false } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/update-user-handoff-notification # Update a User's Handoff Notification Rule `PUT https://api.pagerduty.com/users/{id}/oncall_handoff_notification_rules/{oncall_handoff_notification_rule_id}` Update a User's Handoff Notification Rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `oncall_handoff_notification_rule_id` | string | yes | The oncall handoff notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The User's Handoff Notification Rule to be updated. | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rule` | object | yes | A rule for contacting the user for Handoff Notifications. | | `oncall_handoff_notification_rule.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.notify_advance_in_minutes` | integer | | The delay before firing the rule, in minutes. Minimum: 0. | | `oncall_handoff_notification_rule.handoff_type` | string | yes | The type of handoff being created. One of: `both`, `oncall`, `offcall`. Default: `both`. | | `oncall_handoff_notification_rule.contact_method` | object | yes | | | `oncall_handoff_notification_rule.contact_method.id` | string | yes | Read-only. | | `oncall_handoff_notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `oncall_handoff_notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `oncall_handoff_notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `oncall_handoff_notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "oncall_handoff_notification_rule": { "id": "PXPGF42", "handoff_type": "both", "notify_advance_in_minutes": 60, "contact_method": { "id": "PXPGF42", "type": "email_contact_method" } } } ``` ## Response 200 The User's Handoff Notification Rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oncall_handoff_notification_rule` | object | | A rule for contacting the user for Handoff Notifications. Same fields as `oncall_handoff_notification_rule` above. | Example: Response Example ```json { "oncall_handoff_notification_rule": { "id": "PXPGF42", "handoff_type": "oncall", "notify_advance_in_minutes": 30, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" } } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/update-user-notification-rule # Update a user's notification rule `PUT https://api.pagerduty.com/users/{id}/notification_rules/{notification_rule_id}` Update a user's notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users:contact_methods.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `notification_rule_id` | string | yes | The notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The user's notification rule to be updated. | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | yes | | | `notification_rule.id` | string | | Read-only. | | `notification_rule.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.type` | string | yes | The type of object being created. One of: `assignment_notification_rule`. Default: `assignment_notification_rule`. | | `notification_rule.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.start_delay_in_minutes` | integer | yes | The delay before firing the rule, in minutes. Minimum: 0. | | `notification_rule.contact_method` | object | yes | | | `notification_rule.contact_method.id` | string | yes | Read-only. | | `notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `notification_rule.urgency` | string | yes | Which incident urgency this rule is used for. Account must have the `urgencies` ability to have a low urgency notification rule. One of: `high`, `low`. | Example: Request Example ```json { "notification_rule": { "type": "assignment_notification_rule", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method" }, "urgency": "high" } } ``` ## Response 200 The user's notification rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | | Same fields as `notification_rule` above. | Example: Response Example ```json { "notification_rule": { "id": "PXPGF42", "type": "assignment_notification_rule", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/notification_rules/PPSCXAN", "start_delay_in_minutes": 0, "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42" }, "created_at": "2016-02-01T16:06:27-05:00", "urgency": "high" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/users/update-user-status-update-notification-rule # Update a user's status update notification rule `PUT https://api.pagerduty.com/users/{id}/status_update_notification_rules/{status_update_notification_rule_id}` Update a user's status update notification rule. 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](https://docs.pagerduty.com/developer/api-concepts#users) Scoped OAuth requires: `users.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | | `status_update_notification_rule_id` | string | yes | The status update notification rule ID on the user. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) The user's status update notification rule to be updated. | Field | Type | Required | Description | |---|---|---|---| | `status_update_notification_rule` | object | yes | A rule for contacting the user for Incident Status Updates. | | `status_update_notification_rule.contact_method` | object | yes | | | `status_update_notification_rule.contact_method.id` | string | yes | Read-only. | | `status_update_notification_rule.contact_method.summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `status_update_notification_rule.contact_method.type` | string | yes | One of: `email_contact_method_reference`, `phone_contact_method_reference`, `push_notification_contact_method_reference`, `sms_contact_method_reference`, `whatsapp_contact_method_reference`. | | `status_update_notification_rule.contact_method.self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `status_update_notification_rule.contact_method.html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | Example: Request Example ```json { "status_update_notification_rule": { "contact_method": { "id": "PXPGF42", "type": "email_contact_method" } } } ``` ## Response 200 The user's status update notification rule that was updated. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `notification_rule` | object | | A rule for contacting the user for Incident Status Updates. Same fields as `status_update_notification_rule` above. | Example: Response Example ```json { "status_update_notification_rule": { "id": "PXPGF42", "type": "status_update_notification_rule", "summary": "contact method PXPGF42 used as status_update_notification_rule", "self": "https://api.pagerduty.com/users/PXPGF42/status_update_notification_rules/PPSCXAN", "contact_method": { "id": "PXPGF42", "type": "email_contact_method_reference", "summary": "Work", "self": "https://api.pagerduty.com/users/PXPGF42/contact_methods/PXPGF42", "html_url": null }, "created_at": "2016-02-01T16:06:27-05:00" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 402 Account does not have the abilities to perform the action. Please review the response for the required abilities. You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/vendors/get-vendor # Get a vendor `GET https://api.pagerduty.com/vendors/{id}` Get details about one specific vendor. A PagerDuty Vendor represents a specific type of integration. AWS Cloudwatch, Splunk, Datadog are all examples of vendors For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#vendors) Scoped OAuth requires: `vendors.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The vendor requested ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `vendor` | array of object | yes | | | `vendor[].id` | string | | Read-only. | | `vendor[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `vendor[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `vendor[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `vendor[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `vendor[].name` | string | | The short name of the vendor. Read-only. | | `vendor[].website_url` | string (url) | | URL of the vendor's main website. Read-only. | | `vendor[].logo_url` | string (url) | | URL of a logo identifying the vendor. Read-only. | | `vendor[].thumbnail_url` | string (url) | | URL of a small thumbnail image identifying the vendor. Read-only. | | `vendor[].description` | string | | A short description of this vendor, and common use-cases of integrations for this vendor. Read-only. | | `vendor[].integration_guide_url` | string (url) | | URL of an integration guide for this vendor. Read-only. | Example: Response Example ```json { "vendor": [ { "id": "PZQ6AUS", "type": "vendor", "summary": "Amazon CloudWatch", "self": "https://api.pagerduty.com/vendors/PZQ6AUS", "name": "Amazon CloudWatch", "website_url": "https://aws.amazon.com/cloudwatch", "logo_url": "https://s3.amazonaws.com/pdpartner/cloudwatch_large.png", "thumbnail_url": "https://s3.amazonaws.com/pdpartner/cloudwatch_thumb.png", "description": "Amazon Web Services CloudWatch provides monitoring for AWS cloud resources and customer-run applications. AWS can collect data, gain insight, and alert users to fix problems within applications and organizations. AWS CloudWatch gives system-wide visibility into resource utilization and notifications can be set for when any metrics cross a specified threshold.", "integration_guide_url": "http://www.pagerduty.com/docs/guides/aws-cloudwatch-integration-guide/" } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/vendors/list-vendors # List vendors `GET https://api.pagerduty.com/vendors` List all vendors. A PagerDuty Vendor represents a specific type of integration. AWS Cloudwatch, Splunk, Datadog are all examples of vendors For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#vendors) Scoped OAuth requires: `vendors.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated array of vendors. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | | `vendors` | array of object | yes | | | `vendors[].id` | string | | Read-only. | | `vendors[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `vendors[].type` | string | | A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference. Read-only. | | `vendors[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `vendors[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `vendors[].name` | string | | The short name of the vendor. Read-only. | | `vendors[].website_url` | string (url) | | URL of the vendor's main website. Read-only. | | `vendors[].logo_url` | string (url) | | URL of a logo identifying the vendor. Read-only. | | `vendors[].thumbnail_url` | string (url) | | URL of a small thumbnail image identifying the vendor. Read-only. | | `vendors[].description` | string | | A short description of this vendor, and common use-cases of integrations for this vendor. Read-only. | | `vendors[].integration_guide_url` | string (url) | | URL of an integration guide for this vendor. Read-only. | Example: Response Example ```json { "vendors": [ { "id": "PZQ6AUS", "type": "vendor", "summary": "Amazon CloudWatch", "self": "https://api.pagerduty.com/vendors/PZQ6AUS", "name": "Amazon CloudWatch", "website_url": "https://aws.amazon.com/cloudwatch", "logo_url": "https://s3.amazonaws.com/pdpartner/cloudwatch_large.png", "thumbnail_url": "https://s3.amazonaws.com/pdpartner/cloudwatch_thumb.png", "description": "Amazon Web Services CloudWatch provides monitoring for AWS cloud resources and customer-run applications. AWS can collect data, gain insight, and alert users to fix problems within applications and organizations. AWS CloudWatch gives system-wide visibility into resource utilization and notifications can be set for when any metrics cross a specified threshold.", "integration_guide_url": "http://www.pagerduty.com/docs/guides/aws-cloudwatch-integration-guide/" } ], "limit": 25, "offset": 0, "more": false, "total": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/create-oauth-client # Create an OAuth client `POST https://api.pagerduty.com/webhook_subscriptions/oauth_clients` Create a new OAuth client for webhook subscriptions. The client credentials will be validated by attempting to obtain an access token before creation. Requires admin or owner role permissions. Maximum of 10 OAuth clients per account. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `oauth_client` | object | yes | | | `oauth_client.name` | string | yes | A human-readable name for the OAuth client. Max length: 255. | | `oauth_client.client_id` | string | yes | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_client.client_secret` | string | yes | The OAuth client secret provided by the OAuth server. Max length: 255. | | `oauth_client.scope` | string | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_client.token_url` | string (uri) | yes | The OAuth token endpoint URL. Max length: 255. | | `oauth_client.grant_type` | string | yes | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | Example: Create OAuth Client ```json { "oauth_client": { "name": "PagerDuty Webhook Integration", "client_id": "oauth-client-id", "client_secret": "oauth-secret-id", "token_url": "https://foo.oauth-server.com/oauth_token.do", "grant_type": "client_credentials" } } ``` ## Response 201 OAuth client created successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oauth_client` | object | | | | `oauth_client.id` | string | | The ID of the OAuth client. Read-only. | | `oauth_client.type` | string | yes | The type of object being created. One of: `oauth_client`. Default: `oauth_client`. | | `oauth_client.name` | string | yes | A human-readable name for the OAuth client. Max length: 255. | | `oauth_client.client_id` | string | yes | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_client.scope` | string \| null | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_client.token_url` | string (uri) | yes | The OAuth token endpoint URL. Max length: 255. | | `oauth_client.grant_type` | string | yes | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | | `oauth_client.status` | string | | The current status of the OAuth client. Read-only. One of: `active`, `error`. | Example: Get OAuth Client ```json { "oauth_client": { "id": "AGMEB7F7YJYELCPG4Y5YWMYGXE", "type": "oauth_client", "name": "PagerDuty Webhook Integration", "client_id": "oauth-client-id", "scope": null, "token_url": "https://foo.oauth-server.com/oauth_token.do", "grant_type": "client_credentials", "status": "active" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/create-webhook-subscription # Create a webhook subscription `POST https://api.pagerduty.com/webhook_subscriptions` Creates a new webhook subscription. For more information on webhook subscriptions and how they are used to configure v3 webhooks see the [Webhooks v3 Developer Documentation](https://docs.pagerduty.com/developer/webhooks-overview). Scoped OAuth requires: `webhook_subscriptions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | yes | | | `webhook_subscription.id` | string | | Read-only. | | `webhook_subscription.type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. | | `webhook_subscription.active` | boolean | | Determines whether this subscription will produce webhook events. Default: `true`. | | `webhook_subscription.delivery_method` | object | yes | | | `webhook_subscription.delivery_method.id` | string | | Read-only. | | `webhook_subscription.delivery_method.secret` | string \| null | | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. | | `webhook_subscription.delivery_method.temporarily_disabled` | boolean | | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. | | `webhook_subscription.delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. | | `webhook_subscription.delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. | | `webhook_subscription.delivery_method.custom_headers` | array of object | | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. | | `webhook_subscription.delivery_method.custom_headers[].name` | string | | The header name. | | `webhook_subscription.delivery_method.custom_headers[].value` | string | | The header value. | | `webhook_subscription.description` | string | | A short description of the webhook subscription. | | `webhook_subscription.events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. | | `webhook_subscription.filter` | object | yes | | | `webhook_subscription.filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscription.filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscription.oauth_client` | object | | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. | | `webhook_subscription.oauth_client.id` | string | yes | The ID of the OAuth client. | | `webhook_subscription.oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. | | `webhook_subscription.oauth_client.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. | Example: Example ```json { "webhook_subscription": { "delivery_method": { "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "header-name", "value": "header-value" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client_id": "AGMEB7F7YJYELCPG4Y5YWMYGXE", "type": "webhook_subscription" } } ``` ## Response 200 The webhook subscription that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | yes | Same fields as `webhook_subscription` above. | Example: Example ```json { "webhook_subscription": { "delivery_method": { "id": "PF9KMXH", "secret": null, "temporarily_disabled": false, "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "your-header-name", "value": "-- redacted --" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client": { "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY", "type": "oauth_client_reference", "summary": "PagerDuty Webhook Integration" }, "id": "PY1OL64", "type": "webhook_subscription", "active": true } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/delete-oauth-client # Delete an OAuth client `DELETE https://api.pagerduty.com/webhook_subscriptions/oauth_clients/{id}` Delete an OAuth client. This will also remove the OAuth client association from any webhook subscriptions using it. Requires admin or owner role permissions. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 OAuth client deleted successfully ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/delete-webhook-subscription # Delete a webhook subscription `DELETE https://api.pagerduty.com/webhook_subscriptions/{id}` Deletes a webhook subscription. Scoped OAuth requires: `webhook_subscriptions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The webhook subscription was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/enable-webhook-subscription # Enable a webhook subscription `POST https://api.pagerduty.com/webhook_subscriptions/{id}/enable` Enable a webhook subscription that is temporarily disabled. (This API does not require a request body.) Webhook subscriptions can become temporarily disabled when the subscription's delivery method is repeatedly rejected by the server. Scoped OAuth requires: `webhook_subscriptions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The webhook subscription that was successfully enabled. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | yes | | | `webhook_subscription.id` | string | | Read-only. | | `webhook_subscription.type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. | | `webhook_subscription.active` | boolean | | Determines whether this subscription will produce webhook events. Default: `true`. | | `webhook_subscription.delivery_method` | object | yes | | | `webhook_subscription.delivery_method.id` | string | | Read-only. | | `webhook_subscription.delivery_method.secret` | string \| null | | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. | | `webhook_subscription.delivery_method.temporarily_disabled` | boolean | | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. | | `webhook_subscription.delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. | | `webhook_subscription.delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. | | `webhook_subscription.delivery_method.custom_headers` | array of object | | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. | | `webhook_subscription.delivery_method.custom_headers[].name` | string | | The header name. | | `webhook_subscription.delivery_method.custom_headers[].value` | string | | The header value. | | `webhook_subscription.description` | string | | A short description of the webhook subscription. | | `webhook_subscription.events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. | | `webhook_subscription.filter` | object | yes | | | `webhook_subscription.filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscription.filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscription.oauth_client` | object | | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. | | `webhook_subscription.oauth_client.id` | string | yes | The ID of the OAuth client. | | `webhook_subscription.oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. | | `webhook_subscription.oauth_client.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. | Example: Example ```json { "webhook_subscription": { "delivery_method": { "id": "PF9KMXH", "secret": null, "temporarily_disabled": false, "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "your-header-name", "value": "-- redacted --" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client": { "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY", "type": "oauth_client_reference", "summary": "PagerDuty Webhook Integration" }, "id": "PY1OL64", "type": "webhook_subscription", "active": true } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/get-oauth-client # Get an OAuth client `GET https://api.pagerduty.com/webhook_subscriptions/oauth_clients/{id}` Get details of a specific OAuth client by ID. Requires admin or owner role permissions. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 OAuth client details ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oauth_client` | object | | | | `oauth_client.id` | string | | The ID of the OAuth client. Read-only. | | `oauth_client.type` | string | yes | The type of object being created. One of: `oauth_client`. Default: `oauth_client`. | | `oauth_client.name` | string | yes | A human-readable name for the OAuth client. Max length: 255. | | `oauth_client.client_id` | string | yes | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_client.scope` | string \| null | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_client.token_url` | string (uri) | yes | The OAuth token endpoint URL. Max length: 255. | | `oauth_client.grant_type` | string | yes | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | | `oauth_client.status` | string | | The current status of the OAuth client. Read-only. One of: `active`, `error`. | Example: Get OAuth Client ```json { "oauth_client": { "id": "AGMEB7F7YJYELCPG4Y5YWMYGXE", "type": "oauth_client", "name": "PagerDuty Webhook Integration", "client_id": "oauth-client-id", "scope": null, "token_url": "https://foo.oauth-server.com/oauth_token.do", "grant_type": "client_credentials", "status": "active" } } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/get-webhook-subscription # Get a webhook subscription `GET https://api.pagerduty.com/webhook_subscriptions/{id}` Gets details about an existing webhook subscription. Scoped OAuth requires: `webhook_subscriptions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The webhook subscription that was requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | yes | | | `webhook_subscription.id` | string | | Read-only. | | `webhook_subscription.type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. | | `webhook_subscription.active` | boolean | | Determines whether this subscription will produce webhook events. Default: `true`. | | `webhook_subscription.delivery_method` | object | yes | | | `webhook_subscription.delivery_method.id` | string | | Read-only. | | `webhook_subscription.delivery_method.secret` | string \| null | | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. | | `webhook_subscription.delivery_method.temporarily_disabled` | boolean | | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. | | `webhook_subscription.delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. | | `webhook_subscription.delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. | | `webhook_subscription.delivery_method.custom_headers` | array of object | | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. | | `webhook_subscription.delivery_method.custom_headers[].name` | string | | The header name. | | `webhook_subscription.delivery_method.custom_headers[].value` | string | | The header value. | | `webhook_subscription.description` | string | | A short description of the webhook subscription. | | `webhook_subscription.events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. | | `webhook_subscription.filter` | object | yes | | | `webhook_subscription.filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscription.filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscription.oauth_client` | object | | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. | | `webhook_subscription.oauth_client.id` | string | yes | The ID of the OAuth client. | | `webhook_subscription.oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. | | `webhook_subscription.oauth_client.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. | Example: Example ```json { "webhook_subscription": { "delivery_method": { "id": "PF9KMXH", "secret": null, "temporarily_disabled": false, "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "your-header-name", "value": "-- redacted --" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client": { "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY", "type": "oauth_client_reference", "summary": "PagerDuty Webhook Integration" }, "id": "PY1OL64", "type": "webhook_subscription", "active": true } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/list-oauth-clients # List OAuth clients `GET https://api.pagerduty.com/webhook_subscriptions/oauth_clients` List all OAuth clients for webhook subscriptions. Maximum of 10 clients per account. Requires admin or owner role permissions. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A list of OAuth clients ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oauth_clients` | array of object | | | | `oauth_clients[].id` | string | | The ID of the OAuth client. Read-only. | | `oauth_clients[].type` | string | yes | The type of object being created. One of: `oauth_client`. Default: `oauth_client`. | | `oauth_clients[].name` | string | yes | A human-readable name for the OAuth client. Max length: 255. | | `oauth_clients[].client_id` | string | yes | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_clients[].scope` | string \| null | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_clients[].token_url` | string (uri) | yes | The OAuth token endpoint URL. Max length: 255. | | `oauth_clients[].grant_type` | string | yes | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | | `oauth_clients[].status` | string | | The current status of the OAuth client. Read-only. One of: `active`, `error`. | Example: List OAuth Clients ```json { "oauth_clients": [ { "id": "AGLMVG7ZUZ567GK2HMOWBGNWEU", "type": "oauth_client", "name": "Test OAuth Client", "client_id": "test_client_id", "scope": "read write", "token_url": "https://example.com/oauth/token", "grant_type": "client_credentials", "status": "active" } ] } ``` ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/list-webhook-subscriptions # List webhook subscriptions `GET https://api.pagerduty.com/webhook_subscriptions` List existing webhook subscriptions. The `filter_type` and `filter_id` query parameters may be used to only show subscriptions for a particular _service_ or _team_. For more information on webhook subscriptions and how they are used to configure v3 webhooks see the [Webhooks v3 Developer Documentation](https://docs.pagerduty.com/developer/webhooks-overview). Scoped OAuth requires: `webhook_subscriptions.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The number of results per page. | | `offset` | integer | | Offset to start pagination search results. | | `total` | boolean | | 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. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. | | `filter_type` | string | | The type of resource to filter upon. One of: `account`, `service`, `team`. | | `filter_id` | string | | The id of the resource to filter upon. Required if filter_type is service or team. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A set of webhook subscriptions matching the request. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscriptions` | array of object | yes | | | `webhook_subscriptions[].id` | string | | Read-only. | | `webhook_subscriptions[].type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. | | `webhook_subscriptions[].active` | boolean | | Determines whether this subscription will produce webhook events. Default: `true`. | | `webhook_subscriptions[].delivery_method` | object | yes | | | `webhook_subscriptions[].delivery_method.id` | string | | Read-only. | | `webhook_subscriptions[].delivery_method.secret` | string \| null | | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. | | `webhook_subscriptions[].delivery_method.temporarily_disabled` | boolean | | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. | | `webhook_subscriptions[].delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. | | `webhook_subscriptions[].delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. | | `webhook_subscriptions[].delivery_method.custom_headers` | array of object | | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. | | `webhook_subscriptions[].delivery_method.custom_headers[].name` | string | | The header name. | | `webhook_subscriptions[].delivery_method.custom_headers[].value` | string | | The header value. | | `webhook_subscriptions[].description` | string | | A short description of the webhook subscription. | | `webhook_subscriptions[].events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. | | `webhook_subscriptions[].filter` | object | yes | | | `webhook_subscriptions[].filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscriptions[].filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscriptions[].oauth_client` | object | | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. | | `webhook_subscriptions[].oauth_client.id` | string | yes | The ID of the OAuth client. | | `webhook_subscriptions[].oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. | | `webhook_subscriptions[].oauth_client.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. | | `offset` | integer | | Echoes offset pagination property. Read-only. | | `limit` | integer | | Echoes limit pagination property. Read-only. | | `more` | boolean | | Indicates if there are additional records to return. Read-only. | | `total` | integer \| null | | The total number of records matching the given query. Read-only. | Example: Example ```json { "webhook_subscriptions": [ { "delivery_method": { "id": "PF9KMXH", "secret": null, "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "your-header-name", "value": "-- redacted --" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client": { "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY", "type": "oauth_client_reference", "summary": "PagerDuty Webhook Integration" }, "id": "PY1OL64", "type": "webhook_subscription", "active": true } ], "limit": 25, "offset": 0, "total": null, "more": false } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/test-webhook-subscription # Test a webhook subscription `POST https://api.pagerduty.com/webhook_subscriptions/{id}/ping` Test a webhook subscription. Fires a test event against the webhook subscription. If properly configured, this will deliver the `pagey.ping` webhook event to the destination. Scoped OAuth requires: `webhook_subscriptions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 202 Accepted ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/update-oauth-client # Update an OAuth client `PUT https://api.pagerduty.com/webhook_subscriptions/oauth_clients/{id}` Update an existing OAuth client. Any change will trigger token validation with the OAuth server. Requires admin or owner role permissions. ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) — required | Field | Type | Required | Description | |---|---|---|---| | `oauth_client` | object | yes | | | `oauth_client.name` | string | | A human-readable name for the OAuth client. Max length: 255. | | `oauth_client.client_id` | string | | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_client.client_secret` | string | | The OAuth client secret provided by the OAuth server. Max length: 255. | | `oauth_client.scope` | string | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_client.token_url` | string (uri) | | The OAuth token endpoint URL. Max length: 255. | | `oauth_client.grant_type` | string | | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | Example: Update OAuth Client ```json { "oauth_client": { "name": "Updated ServiceNow Integration", "scope": "read write admin" } } ``` ## Response 200 OAuth client updated successfully ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `oauth_client` | object | | | | `oauth_client.id` | string | | The ID of the OAuth client. Read-only. | | `oauth_client.type` | string | yes | The type of object being created. One of: `oauth_client`. Default: `oauth_client`. | | `oauth_client.name` | string | yes | A human-readable name for the OAuth client. Max length: 255. | | `oauth_client.client_id` | string | yes | The OAuth client ID provided by the OAuth server. Max length: 255. | | `oauth_client.scope` | string \| null | | The OAuth scopes requested for this client. Max length: 255. | | `oauth_client.token_url` | string (uri) | yes | The OAuth token endpoint URL. Max length: 255. | | `oauth_client.grant_type` | string | yes | The OAuth grant type (currently only client_credentials is supported) One of: `client_credentials`. | | `oauth_client.status` | string | | The current status of the OAuth client. Read-only. One of: `active`, `error`. | Example: Get OAuth Client ```json { "oauth_client": { "id": "AGMEB7F7YJYELCPG4Y5YWMYGXE", "type": "oauth_client", "name": "PagerDuty Webhook Integration", "client_id": "oauth-client-id", "scope": null, "token_url": "https://foo.oauth-server.com/oauth_token.do", "grant_type": "client_credentials", "status": "active" } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/webhooks/update-webhook-subscription # Update a webhook subscription `PUT https://api.pagerduty.com/webhook_subscriptions/{id}` Updates an existing webhook subscription. Only the fields being updated need to be included on the request. This operation does not support updating the `delivery_method` of the webhook subscription. Scoped OAuth requires: `webhook_subscriptions.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | | | | `webhook_subscription.description` | string | | A short description of the webhook subscription. | | `webhook_subscription.events` | array of string | | The set of outbound event types the subscription will receive. Min items: 1. Items must be unique. | | `webhook_subscription.filter` | object | | | | `webhook_subscription.filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscription.filter.type` | string | | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscription.active` | boolean | | If true, a webhook will be sent. True is the default state. If false, a webhook will not be sent. | | `webhook_subscription.oauth_client_id` | string \| null | | The ID of the OAuth client to use for authenticating webhook requests. Optional field. | Example: Update Subscribed Events ```json { "webhook_subscription": { "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ] } } ``` ## Response 200 The updated webhook subscription. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `webhook_subscription` | object | yes | | | `webhook_subscription.id` | string | | Read-only. | | `webhook_subscription.type` | string | yes | The type indicating the schema of the object. One of: `webhook_subscription`. Default: `webhook_subscription`. | | `webhook_subscription.active` | boolean | | Determines whether this subscription will produce webhook events. Default: `true`. | | `webhook_subscription.delivery_method` | object | yes | | | `webhook_subscription.delivery_method.id` | string | | Read-only. | | `webhook_subscription.delivery_method.secret` | string \| null | | The secret used to sign webhook payloads. Only provided on the initial create response. Read-only. | | `webhook_subscription.delivery_method.temporarily_disabled` | boolean | | Whether or not this webhook subscription is temporarily disabled. Becomes `true` if the delivery method URL is repeatedly rejected by the server. | | `webhook_subscription.delivery_method.type` | string | yes | Indicates the type of the delivery method. One of: `http_delivery_method`. Default: `http_delivery_method`. | | `webhook_subscription.delivery_method.url` | string (url) | yes | The destination URL for webhook delivery. | | `webhook_subscription.delivery_method.custom_headers` | array of object | | Optional headers to be set on this webhook subscription when sent. The header values are redacted in GET requests, but are not redacted on the webhook when delivered to the webhook's endpoint. | | `webhook_subscription.delivery_method.custom_headers[].name` | string | | The header name. | | `webhook_subscription.delivery_method.custom_headers[].value` | string | | The header value. | | `webhook_subscription.description` | string | | A short description of the webhook subscription. | | `webhook_subscription.events` | array of string | yes | The set of outbound event types the webhook will receive. Min items: 1. Items must be unique. | | `webhook_subscription.filter` | object | yes | | | `webhook_subscription.filter.id` | string | | The id of the object being used as the filter. This field is required for all filter types except account_reference. | | `webhook_subscription.filter.type` | string | yes | The type of object being used as the filter. One of: `account_reference`, `service_reference`, `team_reference`. | | `webhook_subscription.oauth_client` | object | | OAuth client details. This field is populated in responses when oauth_client_id is set. Read-only. | | `webhook_subscription.oauth_client.id` | string | yes | The ID of the OAuth client. | | `webhook_subscription.oauth_client.type` | string | yes | The type of object being referenced. One of: `oauth_client_reference`. Default: `oauth_client_reference`. | | `webhook_subscription.oauth_client.summary` | string | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. Read-only. | Example: Example ```json { "webhook_subscription": { "delivery_method": { "id": "PF9KMXH", "secret": null, "temporarily_disabled": false, "type": "http_delivery_method", "url": "https://example.com/receive_a_pagerduty_webhook", "custom_headers": [ { "name": "your-header-name", "value": "-- redacted --" } ] }, "description": "Sends PagerDuty v3 webhook events somewhere interesting.", "events": [ "incident.acknowledged", "incident.annotated", "incident.delegated", "incident.escalated", "incident.priority_updated", "incident.reassigned", "incident.reopened", "incident.resolved", "incident.responder.added", "incident.responder.replied", "incident.triggered", "incident.unacknowledged" ], "filter": { "id": "P393ZNQ", "type": "service_reference" }, "oauth_client": { "id": "AGLRZQ2PGR5B7EQ52DTT4ZJERY", "type": "oauth_client_reference", "summary": "PagerDuty Webhook Integration" }, "id": "PY1OL64", "type": "webhook_subscription", "active": true } } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ## Response 404 The requested resource was not found. ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/create-workflow-integration-connection # Create Workflow Integration Connection `POST https://api.pagerduty.com/workflows/integrations/{integration_id}/connections` Create a new Workflow Integration Connection. Scoped OAuth requires: `workflow_integrations:connections.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | The ID of the Workflow Integration. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the connection. Read-only. | | `type` | string | | The type of the connection. Read-only. | | `integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `name` | string | yes | The name given to the connection. | | `service_url` | string | | The URL of the service that this connection is associated with. | | `external_id` | string | | The ID of the external system that this connection is used to connect to. | | `external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `scopes` | array of string | | | | `is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `health` | object | | Read-only. | | `health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `health.health_message` | string | | A message describing the health of the connection. Read-only. | | `health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `configuration` | object | | The configuration for this connection. The configuration schema is defined in the Workflow Integration's `configuration_schema` property. It is dynamic based on the specific Workflow Integration. | | `secrets` | object | yes | The secrets for this connection. The secrets schema is defined in the Workflow Integration's `secrets_schema` property. It is dynamic based on the specific Workflow Integration. This field is write-only and will always be `null` on a response so that secrets are not leaked. | | `teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `teams[].team_id` | string | | The ID of the team. | | `teams[].type` | string | | One of: `team_reference`. | | `apps` | array of object | | The app IDs for this connection. | | `apps[].app_id` | string | | The ID of the app. | | `apps[].type` | string | | One of: `pd_app_reference`. | Example: Create or update Workflow Integration Connection example. ```json { "connection": { "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET" }, "secrets": { "Authentication Headers": "x-api-key: 1234abcd" }, "is_default": true, "teams": [], "apps": [] } } ``` ## Response 201 The Workflow Integration Connection that was created. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the connection. Read-only. | | `summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `type` | string | | The type of the connection. Read-only. | | `self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `name` | string | | The name given to the connection. | | `service_url` | string | | The URL of the service that this connection is associated with. | | `external_id` | string | | The ID of the external system that this connection is used to connect to. | | `external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `scopes` | array of string | | | | `is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `health` | object | | Read-only. | | `health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `health.health_message` | string | | A message describing the health of the connection. Read-only. | | `health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `configuration` | object | | The configuration for this connection. | | `secrets` | object | | The secrets for this connection. This will always be `null` on a response so that secrets are not leaked. | | `teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `teams[].team_id` | string | | The ID of the team. | | `teams[].type` | string | | One of: `team_reference`. | | `apps` | array of object | | The app IDs for this connection. | | `apps[].app_id` | string | | The ID of the app. | | `apps[].type` | string | | One of: `pd_app_reference`. | | `created_at` | string (date-time) | | The timestamp of when the connection was created. Read-only. | | `created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `created_by.id` | string | | Unique identifier of the user. Read-only. | | `created_by.summary` | string | | The user's name. Read-only. | | `created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "connection": [ { "id": "5a8e88bb-2acd-4035-8f02-163c10f917b8", "type": "workflow_integration_connection", "integration_id": "http-api", "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "is_default": true, "health": { "is_healthy": true, "last_checked_at": "2024-07-18T21:16:51.511+00:00", "health_message": "Healthy" }, "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET", "Redacted Authentication Headers": "x-api-key: ****" }, "secrets": null, "teams": [], "apps": [], "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "self": "https://api.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/delete-workflow-integration-connection # Delete Workflow Integration Connection `DELETE https://api.pagerduty.com/workflows/integrations/{integration_id}/connections/{id}` Delete a Workflow Integration Connection. Scoped OAuth requires: `workflow_integrations:connections.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | The ID of the Workflow Integration. | | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 204 The Workflow Integration Connection was deleted successfully. ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/get-workflow-integration # Get Workflow Integration `GET https://api.pagerduty.com/workflows/integrations/{id}` Get details about a Workflow Integration. Scoped OAuth requires: `workflow_integrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Workflow Integration requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the integration. Read-only. | | `summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `type` | string | | The type of the resource. Read-only. | | `self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `domain_name` | string | | Will be pagerduty.com. | | `package_name` | string | | The package that the integration is part of. | | `name` | string | | The name of the integration. | | `description` | string | | The description of the integration. | | `icon_svg` | string | | The svg string of the icon for the integration. | | `tags` | array of string | | A list of tags applied to the integration. | | `search_keywords` | array of string | | A list of keywords that match this integration. | | `is_deprecated` | boolean | | Whether or not the integration is deprecated. | | `entitled` | boolean | | Whether or not the integration is entitled. | | `application` | string | | The application that this integration is associated with. | | `configuration_schema` | object | | The JSON schema for the configuration of the integration. This is a dynamic field and is different for every integration. | | `secrets_schema` | object | | The JSON schema for the secrets of the integration. This is a dynamic field and is different for every integration. | | `created_at` | string (date-time) | | Read-only. | | `created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `created_by.id` | string | | Unique identifier of the user. Read-only. | | `created_by.summary` | string | | The user's name. Read-only. | | `created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "integration": [ { "id": "http-api", "type": "workflow_integration", "domain_name": "pagerduty.com", "package_name": "http-api", "name": "Web API", "description": "Create fast, custom connections to apps without integrations.", "icon_svg": "\n\n\n", "tags": [ "integration" ], "search_keywords": [ "web", "api", "rest", "http", "headers" ], "is_deprecated": false, "entitled": true, "application": null, "configuration_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.pagerduty.com/workflows/integrations/http-api/schemas/configuration.json", "title": "Web API Integration Configuration", "description": "The configuration of a workflow integration connection to Web API", "type": "object", "properties": { "Redacted Authentication Headers": { "type": "text", "description": "Stores the redacted versions of the sensitive authentication headers", "is_hidden": true, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 2 }, "Allowed Hostnames": { "type": "text", "description": "Enter the hostnames to allow sending these credentials to, one per line. An asterisk (*) may be used for subdomains. Ex: \"example.com\", \"subdomain.example.com\" or \"*.example.com\"", "is_hidden": false, "advanced": false, "metadata": "{\"format\":\"textarea\"}", "default_value": null, "restrictions": null, "display_order": 3, "format": "TEXTAREA" }, "Health Check URL": { "type": "text", "description": "Enter a url to monitor the health of this connection.", "is_hidden": false, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 4 }, "Health Check Method": { "type": "singleChoice", "description": "Select which HTTP method to use for the health check request.", "is_hidden": false, "advanced": false, "metadata": "", "default_value": "HEAD", "restrictions": { "choices": [ "HEAD", "GET" ] }, "display_order": 5 }, "Existing Connection": { "type": "connection", "description": "Existing connection to update, if any", "is_hidden": true, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 6, "connection_type_id": "pagerduty.com:http-api:integration:1" } }, "required": [ "Allowed Hostnames" ] }, "secrets_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.pagerduty.com/workflows/integrations/http-api/schemas/secrets.json", "title": "Web API Integration Secrets", "description": "The secrets of a workflow integration connection to Web API", "type": "object", "properties": { "Authentication Headers": { "type": "text", "description": "Enter the headers to include in Web API calls made with this connection, one per line. Ex: \"Authorization: Bearer XXXX\"", "is_hidden": false, "advanced": false, "metadata": "{\"format\":\"textarea\"}", "default_value": null, "restrictions": null, "display_order": 1, "format": "TEXTAREA" }, "required": [ "Authentication Headers" ] } }, "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api", "self": "https://api.pagerduty.com/workflows/integrations/http-api", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/get-workflow-integration-connection # Get Workflow Integration Connection `GET https://api.pagerduty.com/workflows/integrations/{integration_id}/connections/{id}` Get details about a Workflow Integration Connection. Scoped OAuth requires: `workflow_integrations:connections.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | The ID of the Workflow Integration. | | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 The Workflow Integration Connection requested. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the connection. Read-only. | | `summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `type` | string | | The type of the connection. Read-only. | | `self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `name` | string | | The name given to the connection. | | `service_url` | string | | The URL of the service that this connection is associated with. | | `external_id` | string | | The ID of the external system that this connection is used to connect to. | | `external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `scopes` | array of string | | | | `is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `health` | object | | Read-only. | | `health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `health.health_message` | string | | A message describing the health of the connection. Read-only. | | `health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `configuration` | object | | The configuration for this connection. | | `secrets` | object | | The secrets for this connection. This will always be `null` on a response so that secrets are not leaked. | | `teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `teams[].team_id` | string | | The ID of the team. | | `teams[].type` | string | | One of: `team_reference`. | | `apps` | array of object | | The app IDs for this connection. | | `apps[].app_id` | string | | The ID of the app. | | `apps[].type` | string | | One of: `pd_app_reference`. | | `created_at` | string (date-time) | | The timestamp of when the connection was created. Read-only. | | `created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `created_by.id` | string | | Unique identifier of the user. Read-only. | | `created_by.summary` | string | | The user's name. Read-only. | | `created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "connection": [ { "id": "5a8e88bb-2acd-4035-8f02-163c10f917b8", "type": "workflow_integration_connection", "integration_id": "http-api", "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "is_default": true, "health": { "is_healthy": true, "last_checked_at": "2024-07-18T21:16:51.511+00:00", "health_message": "Healthy" }, "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET", "Redacted Authentication Headers": "x-api-key: ****" }, "secrets": null, "teams": [], "apps": [], "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "self": "https://api.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/list-workflow-integration-connections # List all Workflow Integration Connections `GET https://api.pagerduty.com/workflows/integrations/connections` List all Workflow Integration Connections. Scoped OAuth requires: `workflow_integrations:connections.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `name` | string | | Filter Integrations by partial name. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated list of Workflow Integration Connections. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | | | `next_cursor` | string \| null | yes | | | `connections` | array of object | yes | | | `connections[].id` | string | | The ID of the connection. Read-only. | | `connections[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `connections[].type` | string | | The type of the connection. Read-only. | | `connections[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `connections[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `connections[].integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `connections[].name` | string | | The name given to the connection. | | `connections[].service_url` | string | | The URL of the service that this connection is associated with. | | `connections[].external_id` | string | | The ID of the external system that this connection is used to connect to. | | `connections[].external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `connections[].scopes` | array of string | | | | `connections[].is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `connections[].health` | object | | Read-only. | | `connections[].health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `connections[].health.health_message` | string | | A message describing the health of the connection. Read-only. | | `connections[].health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `connections[].configuration` | object | | The configuration for this connection. | | `connections[].secrets` | object | | The secrets for this connection. This will always be `null` on a response so that secrets are not leaked. | | `connections[].teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `connections[].teams[].team_id` | string | | The ID of the team. | | `connections[].teams[].type` | string | | One of: `team_reference`. | | `connections[].apps` | array of object | | The app IDs for this connection. | | `connections[].apps[].app_id` | string | | The ID of the app. | | `connections[].apps[].type` | string | | One of: `pd_app_reference`. | | `connections[].created_at` | string (date-time) | | The timestamp of when the connection was created. Read-only. | | `connections[].created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `connections[].created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `connections[].created_by.id` | string | | Unique identifier of the user. Read-only. | | `connections[].created_by.summary` | string | | The user's name. Read-only. | | `connections[].created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `connections[].created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "connections": [ { "id": "5a8e88bb-2acd-4035-8f02-163c10f917b8", "type": "workflow_integration_connection", "integration_id": "http-api", "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "health": { "is_healthy": true, "last_checked_at": "2024-07-18T21:16:51.511+00:00", "health_message": "Healthy" }, "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET", "Redacted Authentication Headers": "x-api-key: ****" }, "secrets": null, "teams": [], "apps": [], "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "self": "https://api.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/list-workflow-integration-connections-by-integration # List Workflow Integration Connections `GET https://api.pagerduty.com/workflows/integrations/{integration_id}/connections` List all Workflow Integration Connections for a specific Workflow Integration. Scoped OAuth requires: `workflow_integrations:connections.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | The ID of the Workflow Integration. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `name` | string | | Filter Integrations by partial name. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated list of Workflow Integration Connections. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | | | `next_cursor` | string \| null | yes | | | `connections` | array of object | yes | | | `connections[].id` | string | | The ID of the connection. Read-only. | | `connections[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `connections[].type` | string | | The type of the connection. Read-only. | | `connections[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `connections[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `connections[].integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `connections[].name` | string | | The name given to the connection. | | `connections[].service_url` | string | | The URL of the service that this connection is associated with. | | `connections[].external_id` | string | | The ID of the external system that this connection is used to connect to. | | `connections[].external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `connections[].scopes` | array of string | | | | `connections[].is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `connections[].health` | object | | Read-only. | | `connections[].health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `connections[].health.health_message` | string | | A message describing the health of the connection. Read-only. | | `connections[].health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `connections[].configuration` | object | | The configuration for this connection. | | `connections[].secrets` | object | | The secrets for this connection. This will always be `null` on a response so that secrets are not leaked. | | `connections[].teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `connections[].teams[].team_id` | string | | The ID of the team. | | `connections[].teams[].type` | string | | One of: `team_reference`. | | `connections[].apps` | array of object | | The app IDs for this connection. | | `connections[].apps[].app_id` | string | | The ID of the app. | | `connections[].apps[].type` | string | | One of: `pd_app_reference`. | | `connections[].created_at` | string (date-time) | | The timestamp of when the connection was created. Read-only. | | `connections[].created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `connections[].created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `connections[].created_by.id` | string | | Unique identifier of the user. Read-only. | | `connections[].created_by.summary` | string | | The user's name. Read-only. | | `connections[].created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `connections[].created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "connections": [ { "id": "5a8e88bb-2acd-4035-8f02-163c10f917b8", "type": "workflow_integration_connection", "integration_id": "http-api", "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "is_default": "true,", "health": { "is_healthy": true, "last_checked_at": "2024-07-18T21:16:51.511+00:00", "health_message": "Healthy" }, "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET", "Redacted Authentication Headers": "x-api-key: ****" }, "secrets": null, "teams": [], "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "self": "https://api.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ], "limit": 10, "next_cursor": null } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/list-workflow-integrations # List Workflow Integrations `GET https://api.pagerduty.com/workflows/integrations` List available Workflow Integrations. Scoped OAuth requires: `workflow_integrations.read` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `limit` | integer | | The minimum of the `limit` parameter used in the request or the maximum request size of the API. | | `cursor` | string | | Optional parameter used to request the "next" set of results from an API. The value provided here is most commonly obtained from the `next_cursor` field of the previous request. When no value is provided, the request starts at the beginning of the result set. | | `include_deprecated` | boolean | | Whether to include deprecated Integrations in the response. Default: `false`. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Response 200 A paginated list of Workflow Integrations. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `limit` | integer | yes | | | `next_cursor` | string \| null | yes | | | `integrations` | array of object | yes | | | `integrations[].id` | string | | The ID of the integration. Read-only. | | `integrations[].summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `integrations[].type` | string | | The type of the resource. Read-only. | | `integrations[].self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `integrations[].html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integrations[].domain_name` | string | | Will be pagerduty.com. | | `integrations[].package_name` | string | | The package that the integration is part of. | | `integrations[].name` | string | | The name of the integration. | | `integrations[].description` | string | | The description of the integration. | | `integrations[].icon_svg` | string | | The svg string of the icon for the integration. | | `integrations[].tags` | array of string | | A list of tags applied to the integration. | | `integrations[].search_keywords` | array of string | | A list of keywords that match this integration. | | `integrations[].is_deprecated` | boolean | | Whether or not the integration is deprecated. | | `integrations[].entitled` | boolean | | Whether or not the integration is entitled. | | `integrations[].application` | string | | The application that this integration is associated with. | | `integrations[].configuration_schema` | object | | The JSON schema for the configuration of the integration. This is a dynamic field and is different for every integration. | | `integrations[].secrets_schema` | object | | The JSON schema for the secrets of the integration. This is a dynamic field and is different for every integration. | | `integrations[].created_at` | string (date-time) | | Read-only. | | `integrations[].created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `integrations[].created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `integrations[].created_by.id` | string | | Unique identifier of the user. Read-only. | | `integrations[].created_by.summary` | string | | The user's name. Read-only. | | `integrations[].created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integrations[].created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "integrations": [ { "id": "http-api", "type": "workflow_integration", "domain_name": "pagerduty.com", "package_name": "http-api", "name": "Web API", "description": "Create fast, custom connections to apps without integrations.", "icon_svg": "\n\n\n", "tags": [ "integration" ], "search_keywords": [ "web", "api", "rest", "http", "headers" ], "is_deprecated": false, "entitled": true, "application": null, "configuration_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.pagerduty.com/workflows/integrations/http-api/schemas/configuration.json", "title": "Web API Integration Configuration", "description": "The configuration of a workflow integration connection to Web API", "type": "object", "properties": { "Redacted Authentication Headers": { "type": "text", "description": "Stores the redacted versions of the sensitive authentication headers", "is_hidden": true, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 2 }, "Allowed Hostnames": { "type": "text", "description": "Enter the hostnames to allow sending these credentials to, one per line. An asterisk (*) may be used for subdomains. Ex: \"example.com\", \"subdomain.example.com\" or \"*.example.com\"", "is_hidden": false, "advanced": false, "metadata": "{\"format\":\"textarea\"}", "default_value": null, "restrictions": null, "display_order": 3, "format": "TEXTAREA" }, "Health Check URL": { "type": "text", "description": "Enter a url to monitor the health of this connection.", "is_hidden": false, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 4 }, "Health Check Method": { "type": "singleChoice", "description": "Select which HTTP method to use for the health check request.", "is_hidden": false, "advanced": false, "metadata": "", "default_value": "HEAD", "restrictions": { "choices": [ "HEAD", "GET" ] }, "display_order": 5 }, "Existing Connection": { "type": "connection", "description": "Existing connection to update, if any", "is_hidden": true, "advanced": false, "metadata": "", "default_value": null, "restrictions": null, "display_order": 6, "connection_type_id": "pagerduty.com:http-api:integration:1" } }, "required": [ "Allowed Hostnames" ] }, "secrets_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.pagerduty.com/workflows/integrations/http-api/schemas/secrets.json", "title": "Web API Integration Secrets", "description": "The secrets of a workflow integration connection to Web API", "type": "object", "properties": { "Authentication Headers": { "type": "text", "description": "Enter the headers to include in Web API calls made with this connection, one per line. Ex: \"Authorization: Bearer XXXX\"", "is_hidden": false, "advanced": false, "metadata": "{\"format\":\"textarea\"}", "default_value": null, "restrictions": null, "display_order": 1, "format": "TEXTAREA" }, "required": [ "Authentication Headers" ] } }, "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api", "self": "https://api.pagerduty.com/workflows/integrations/http-api", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ], "limit": 10, "next_cursor": "WyJtM2RlbW8ucGQtc3RhZ2luZy5jb206Z2l0aHViOmludGVncmF0aW9uOjMiXQ==" } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/rest/workflow-integrations/update-workflow-integration-connection # Update Workflow Integration Connection `PATCH https://api.pagerduty.com/workflows/integrations/{integration_id}/connections/{id}` Update an existing Workflow Integration Connection. Scoped OAuth requires: `workflow_integrations:connections.write` ## Authorization - **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `integration_id` | string | yes | The ID of the Workflow Integration. | | `id` | string | yes | The ID of the resource. | ## Header parameters | Name | Type | Required | Description | |---|---|---|---| | `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. | ## Request body (`application/json`) | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the connection. Read-only. | | `type` | string | | The type of the connection. Read-only. | | `integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `name` | string | yes | The name given to the connection. | | `service_url` | string | | The URL of the service that this connection is associated with. | | `external_id` | string | | The ID of the external system that this connection is used to connect to. | | `external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `scopes` | array of string | | | | `is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `health` | object | | Read-only. | | `health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `health.health_message` | string | | A message describing the health of the connection. Read-only. | | `health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `configuration` | object | | The configuration for this connection. The configuration schema is defined in the Workflow Integration's `configuration_schema` property. It is dynamic based on the specific Workflow Integration. | | `secrets` | object | yes | The secrets for this connection. The secrets schema is defined in the Workflow Integration's `secrets_schema` property. It is dynamic based on the specific Workflow Integration. This field is write-only and will always be `null` on a response so that secrets are not leaked. | | `teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `teams[].team_id` | string | | The ID of the team. | | `teams[].type` | string | | One of: `team_reference`. | | `apps` | array of object | | The app IDs for this connection. | | `apps[].app_id` | string | | The ID of the app. | | `apps[].type` | string | | One of: `pd_app_reference`. | Example: Create or update Workflow Integration Connection example. ```json { "connection": { "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET" }, "secrets": { "Authentication Headers": "x-api-key: 1234abcd" }, "is_default": true, "teams": [], "apps": [] } } ``` ## Response 200 The updated Workflow Integration Connection. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `id` | string | | The ID of the connection. Read-only. | | `summary` | string \| null | | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. | | `type` | string | | The type of the connection. Read-only. | | `self` | string \| null (url) | | the API show URL at which the object is accessible. Read-only. | | `html_url` | string \| null (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `integration_id` | string | | The integration ID that this connection is associated with. Read-only. | | `name` | string | | The name given to the connection. | | `service_url` | string | | The URL of the service that this connection is associated with. | | `external_id` | string | | The ID of the external system that this connection is used to connect to. | | `external_id_label` | string | | The label of the external system that this connection is used to connect to. | | `scopes` | array of string | | | | `is_default` | boolean | | Whether or not this connection is the default connection for this integration. | | `health` | object | | Read-only. | | `health.is_healthy` | boolean | | Whether or not the connection is healthy. Read-only. | | `health.health_message` | string | | A message describing the health of the connection. Read-only. | | `health.last_checked_at` | string (date-time) | | The timestamp of the last health check. Read-only. | | `configuration` | object | | The configuration for this connection. | | `secrets` | object | | The secrets for this connection. This will always be `null` on a response so that secrets are not leaked. | | `teams` | array of object | | The teams whose managers are allowed to use or edit this connection. | | `teams[].team_id` | string | | The ID of the team. | | `teams[].type` | string | | One of: `team_reference`. | | `apps` | array of object | | The app IDs for this connection. | | `apps[].app_id` | string | | The ID of the app. | | `apps[].type` | string | | One of: `pd_app_reference`. | | `created_at` | string (date-time) | | The timestamp of when the connection was created. Read-only. | | `created_by` | object, nullable | | Reference to the user who created this connection. Read-only. | | `created_by.type` | string | | Type of the referenced object. Read-only. One of: `user_reference`. | | `created_by.id` | string | | Unique identifier of the user. Read-only. | | `created_by.summary` | string | | The user's name. Read-only. | | `created_by.html_url` | string (url) | | a URL at which the entity is uniquely displayed in the Web app. Read-only. | | `created_by.self` | string (url) | | the API show URL at which the object is accessible. Read-only. | Example: Response Example ```json { "connection": [ { "id": "5a8e88bb-2acd-4035-8f02-163c10f917b8", "type": "workflow_integration_connection", "integration_id": "http-api", "name": "My Connection", "service_url": "https://webhook.site", "external_id": "My Connection", "external_id_label": "Connection Name", "is_default": true, "health": { "is_healthy": true, "last_checked_at": "2024-07-18T21:16:51.511+00:00", "health_message": "Healthy" }, "configuration": { "Health Check URL": "https://example.com/health", "Allowed Hostnames": "webhook.site", "Health Check Method": "GET", "Redacted Authentication Headers": "x-api-key: ****" }, "secrets": null, "teams": [], "apps": [], "html_url": "https://subdomain.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "self": "https://api.pagerduty.com/workflows/integrations/http-api/connections/5a8e88bb-2acd-4035-8f02-163c10f917b8", "created_at": "2024-06-18T18:41:27.1+00:00", "created_by": { "id": "P7F68N8", "type": "user_reference", "summary": "John Smith", "html_url": "https://subdomain.pagerduty.com/users/P7F68N8", "self": "https://api.pagerduty.com/users/P7F68N8" } } ] } ``` ## Response 400 Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 401 Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 403 Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 404 The requested resource was not found. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Response 429 Too many requests have been made, the rate limit has been reached. ### `application/json` | Field | Type | Required | Description | |---|---|---|---| | `error` | object | | | | `error.code` | integer | | Read-only. | | `error.message` | string | | Error message string. Read-only. | | `error.errors` | array of string | | Read-only. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/service-provider-metadata/get-resource-types # Get SCIM Resource Types `GET https://api.pagerduty.com/scim/v2/ResourceTypes` Retrieves the SCIM resource types supported by the service provider. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Response 200 SCIM Resource Types List ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `Resources` | array of object | yes | A multi-valued list of complex objects containing the requested resources. Default: `[]`. | | `Resources[].endpoint` | string | yes | The resource type's HTTP-addressable endpoint relative to the base URL. Min length: 1. Pattern: `^/.*`. | | `Resources[].meta` | object | yes | | | `Resources[].meta.resourceType` | string | yes | The resource type. | | `Resources[].name` | string | yes | The resource type name. Min length: 1. | | `Resources[].schema` | string (uri) | yes | The resource type's primary/base schema URI. Pattern: `^urn:.*`. | | `Resources[].schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:ResourceType"]`. Min items: 1. Items must be unique. | | `itemsPerPage` | integer | yes | The number of resources returned in a list response page. Default: `100`. Minimum: 0. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:ListResponse"]`. Min items: 1. Items must be unique. | | `startIndex` | integer | yes | The 1-based index of the first result in the current set of query results. Default: `1`. Minimum: 1. | | `totalResults` | integer | yes | The total number of results matching the client query. Default: `0`. Minimum: 0. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/service-provider-metadata/get-schema # Get individual SCIM Schema by ID `GET https://api.pagerduty.com/scim/v2/Schemas/{id}` Retrieves an individual SCIM Schema by ID. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the schema targeted in this request. | ## Response 200 SCIM Schema ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `attributes` | array of object | yes | A complex type that specifies the set of attributes that make up the schema. | | `attributes[].canonicalValues` | array of string | | A list of canonical values. When specified, service providers MUST restrict accepted values to the specified values. | | `attributes[].caseExact` | boolean | yes | A Boolean value indicating whether the attribute is case sensitive. | | `attributes[].description` | string | yes | The attribute's human-readable description. Min length: 1. | | `attributes[].multiValued` | boolean | yes | A Boolean value indicating whether the attribute can have multiple values. | | `attributes[].mutability` | string | yes | Indicates whether the attribute is modifiable. One of: `readOnly`, `readWrite`, `immutable`, `writeOnly`. | | `attributes[].name` | string | yes | The attribute's name. Min length: 1. | | `attributes[].required` | boolean | yes | A Boolean value indicating whether the attribute is required. | | `attributes[].returned` | string | yes | Indicates when the attribute is returned. One of: `always`, `never`, `default`, `request`. | | `attributes[].subAttributes` | array of object | | List of sub-attributes for complex attributes. | | `attributes[].type` | string | yes | The attribute's data type. One of: `string`, `boolean`, `decimal`, `integer`, `dateTime`, `reference`, `complex`. | | `attributes[].uniqueness` | string | yes | Indicates how unique a value must be. One of: `none`, `server`, `global`. | | `description` | string | yes | The schema's human-readable description. Min length: 1. | | `id` | string (uri) | yes | The unique identifier for the schema. Min length: 1. Pattern: `^urn:.*`. | | `meta` | object | yes | | | `meta.resourceType` | string | yes | The resource type. | | `name` | string | yes | The schema's human-readable name. Min length: 1. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:Schema"]`. Min items: 1. Items must be unique. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 404 Schema Not Found ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/service-provider-metadata/get-schemas # Get SCIM Schemas `GET https://api.pagerduty.com/scim/v2/Schemas` Retrieves the SCIM schemas supported by the service provider. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Response 200 SCIM Schemas List ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `Resources` | array of object | yes | A multi-valued list of complex objects containing the requested resources. Default: `[]`. | | `Resources[].attributes` | array of object | yes | A complex type that specifies the set of attributes that make up the schema. | | `Resources[].attributes[].canonicalValues` | array of string | | A list of canonical values. When specified, service providers MUST restrict accepted values to the specified values. | | `Resources[].attributes[].caseExact` | boolean | yes | A Boolean value indicating whether the attribute is case sensitive. | | `Resources[].attributes[].description` | string | yes | The attribute's human-readable description. Min length: 1. | | `Resources[].attributes[].multiValued` | boolean | yes | A Boolean value indicating whether the attribute can have multiple values. | | `Resources[].attributes[].mutability` | string | yes | Indicates whether the attribute is modifiable. One of: `readOnly`, `readWrite`, `immutable`, `writeOnly`. | | `Resources[].attributes[].name` | string | yes | The attribute's name. Min length: 1. | | `Resources[].attributes[].required` | boolean | yes | A Boolean value indicating whether the attribute is required. | | `Resources[].attributes[].returned` | string | yes | Indicates when the attribute is returned. One of: `always`, `never`, `default`, `request`. | | `Resources[].attributes[].subAttributes` | array of object | | List of sub-attributes for complex attributes. | | `Resources[].attributes[].type` | string | yes | The attribute's data type. One of: `string`, `boolean`, `decimal`, `integer`, `dateTime`, `reference`, `complex`. | | `Resources[].attributes[].uniqueness` | string | yes | Indicates how unique a value must be. One of: `none`, `server`, `global`. | | `Resources[].description` | string | yes | The schema's human-readable description. Min length: 1. | | `Resources[].id` | string (uri) | yes | The unique identifier for the schema. Min length: 1. Pattern: `^urn:.*`. | | `Resources[].meta` | object | yes | | | `Resources[].meta.resourceType` | string | yes | The resource type. | | `Resources[].name` | string | yes | The schema's human-readable name. Min length: 1. | | `Resources[].schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:Schema"]`. Min items: 1. Items must be unique. | | `itemsPerPage` | integer | yes | The number of resources returned in a list response page. Default: `100`. Minimum: 0. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:ListResponse"]`. Min items: 1. Items must be unique. | | `startIndex` | integer | yes | The 1-based index of the first result in the current set of query results. Default: `1`. Minimum: 1. | | `totalResults` | integer | yes | The total number of results matching the client query. Default: `0`. Minimum: 0. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/service-provider-metadata/get-service-provider-config # Get SCIM Service Provider Configuration `GET https://api.pagerduty.com/scim/v2/ServiceProviderConfig` Retrieves the SCIM Service Provider Configuration. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Response 200 SCIM Service Provider Configuration ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `authenticationSchemes` | array of object | yes | A list of supported authentication schemes. Min items: 1. | | `authenticationSchemes[].description` | string | yes | A description of the authentication scheme. Min length: 1. | | `authenticationSchemes[].documentationUri` | string (uri) | | An HTTP-addressable URL pointing to the authentication scheme's usage documentation. Pattern: `^https?://.*`. | | `authenticationSchemes[].name` | string | yes | The name of the authentication scheme. Min length: 1. | | `authenticationSchemes[].primary` | boolean | | A Boolean value indicating whether this is the primary authentication scheme. | | `authenticationSchemes[].specUri` | string (uri) | | A URI that points to the specification of the authentication scheme. Pattern: `^https?://.*`. | | `authenticationSchemes[].type` | string | yes | The type of authentication scheme. One of: `oauthbearertoken`, `oauth`, `oauth2`, `httpbasic`, `httpdigest`, `apikey`. Min length: 1. | | `bulk` | object | yes | A complex type that specifies bulk configuration options. | | `bulk.maxOperations` | integer | yes | An integer value specifying the maximum number of operations. | | `bulk.maxPayloadSize` | integer | yes | An integer value specifying the maximum payload size in bytes. | | `bulk.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | | `changePassword` | object | yes | A complex type that specifies change password configuration options. | | `changePassword.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | | `documentationUri` | string \| null (uri) | | An HTTP-addressable URL pointing to the service provider's documentation. Pattern: `^https?://.*`. | | `etag` | object | yes | A complex type that specifies ETag configuration options. | | `etag.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | | `filter` | object | yes | A complex type that specifies filter configuration options. | | `filter.maxResults` | integer | yes | An integer value specifying the maximum number of results returned. | | `filter.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | | `meta` | object | yes | | | `meta.resourceType` | string | yes | The resource type. | | `patch` | object | yes | A complex type that specifies PATCH configuration options. | | `patch.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"]`. Min items: 1. Items must be unique. | | `sort` | object | yes | A complex type that specifies sort configuration options. | | `sort.supported` | boolean | yes | A Boolean value specifying whether the operation is supported. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/create-user # Create user `POST https://api.pagerduty.com/scim/v2/Users` Creates a new user with the provided details. Scoped OAuth requires: `users.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Request body (`application/json`) SCIM User Create Params | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `roles` | array of object | | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The `roles` field accepts two formats: Format 1 - Using the primary field: ```json {"roles": [{"value": "user", "primary": true}]} ``` *Required*: `value` (role name), `primary` (must be `true`) *Optional*: `type` (can be any string value, will be ignored and default to `"base"`) Format 2 - Using the type field: ```json {"roles": [{"value": "user", "type": "base"}]} ``` *Required*: `value` (role name), `type` (must be `"base"`) *Optional*: `primary` (must be `true` if included) The role is not required when creating a user. If not set, a default role will be assigned. Valid user roles are defined in the PagerDuty Public API documentation: https://developer.pagerduty.com/api-reference/4cb4fd0f5444a-create-a-user The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | | Whether this is the primary role (must be true) One of: `true`. | | `roles[].type` | string | | Role type (can be any string when primary=true, must be 'base' otherwise) | | `roles[].value` | string | | Role name. | | `schemas` | array of string (uri) | | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 201 SCIM User ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `meta` | object | yes | Read-only. | | `meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | yes | One of: `true`. | | `roles[].type` | string | yes | One of: `base`. | | `roles[].value` | string | yes | | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/delete-user # Delete a user `DELETE https://api.pagerduty.com/scim/v2/Users/{id}` Deletes a user by their unique identifier. Scoped OAuth requires: `users.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the user targeted in this request. | ## Response 204 No Content ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 404 Not Found ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/get-user # Get user `GET https://api.pagerduty.com/scim/v2/Users/{id}` Retrieves a user by their unique identifier. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the user targeted in this request. | ## Response 200 SCIM User ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `meta` | object | yes | Read-only. | | `meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | yes | One of: `true`. | | `roles[].type` | string | yes | One of: `base`. | | `roles[].value` | string | yes | | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 404 Not Found ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/list-users # List users `GET https://api.pagerduty.com/scim/v2/Users` Retrieves a list of users based on the provided query parameters. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `startIndex` | integer | | The 1-based index of the first result. | | `count` | integer | | Specifies the desired maximum number of query results per page. | | `filter` | string | | A filter expression to apply to the query. The only supported filters are by userName and externalId. | ## Response 200 SCIM User List ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `Resources` | array of object | yes | A multi-valued list of complex objects containing the requested resources. Default: `[]`. | | `Resources[].active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `Resources[].displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `Resources[].entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `Resources[].entitlements[].type` | string | yes | One of: `license`. | | `Resources[].entitlements[].value` | string | yes | | | `Resources[].externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `Resources[].id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `Resources[].meta` | object | yes | Read-only. | | `Resources[].meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `Resources[].roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `Resources[].roles[].primary` | boolean | yes | One of: `true`. | | `Resources[].roles[].type` | string | yes | One of: `base`. | | `Resources[].roles[].value` | string | yes | | | `Resources[].schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `Resources[].timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `Resources[].title` | string \| null | | The job title of the User. | | `Resources[].userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | | `itemsPerPage` | integer | yes | The number of resources returned in a list response page. Default: `100`. Minimum: 0. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:ListResponse"]`. Min items: 1. Items must be unique. | | `startIndex` | integer | yes | The 1-based index of the first result in the current set of query results. Default: `1`. Minimum: 1. | | `totalResults` | integer | yes | The total number of results matching the client query. Default: `0`. Minimum: 0. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/patch-user # Patch a user `PATCH https://api.pagerduty.com/scim/v2/Users/{id}` Performs a SCIM PATCH operation on a user. Supports: - Replacement of specific attributes using the 'path' parameter - Full or partial update using the 'value' parameter without a path - Setting 'active' to false to delete the user (returns 204 No Content) - Removing attributes using the 'remove' operation. Only optional attributes can be removed. Scoped OAuth requires: `users.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the user targeted in this request. | ## Request body (`application/json`) SCIM Patch Operation | Field | Type | Required | Description | |---|---|---|---| | `Operations` | array of object | yes | Array of one or more patch operations to be applied to the resource. Min items: 1. | | `Operations[].op` | string | yes | The PATCH operation to perform. | | `Operations[].path` | string \| null | | The path to the attribute to be updated. | | `Operations[].value` | | | The value to be updated in the operation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:PatchOp"]`. Min items: 1. Items must be unique. | ## Response 200 SCIM User ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `meta` | object | yes | Read-only. | | `meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | yes | One of: `true`. | | `roles[].type` | string | yes | One of: `base`. | | `roles[].value` | string | yes | | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 204 No Content ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 404 Not Found ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement). --- URL: https://docs.pagerduty.com/developer/api/reference/scim/users/update-user # Update user `PUT https://api.pagerduty.com/scim/v2/Users/{id}` Updates an existing user with the provided details. Scoped OAuth requires: `users.write` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | yes | The ID of the user targeted in this request. | ## Request body (`application/json`) SCIM User Update Params | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `id` | string | | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `roles` | array of object | | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The `roles` field accepts two formats: Format 1 - Using the primary field: ```json {"roles": [{"value": "user", "primary": true}]} ``` *Required*: `value` (role name), `primary` (must be `true`) *Optional*: `type` (can be any string value, will be ignored and default to `"base"`) Format 2 - Using the type field: ```json {"roles": [{"value": "user", "type": "base"}]} ``` *Required*: `value` (role name), `type` (must be `"base"`) *Optional*: `primary` (must be `true` if included) The role is not required when creating a user. If not set, a default role will be assigned. Valid user roles are defined in the PagerDuty Public API documentation: https://developer.pagerduty.com/api-reference/4cb4fd0f5444a-create-a-user The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | | Whether this is the primary role (must be true) One of: `true`. | | `roles[].type` | string | | Role type (can be any string when primary=true, must be 'base' otherwise) | | `roles[].value` | string | | Role name. | | `schemas` | array of string (uri) | | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 200 SCIM User ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `entitlements[].type` | string | yes | One of: `license`. | | `entitlements[].value` | string | yes | | | `externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `meta` | object | yes | Read-only. | | `meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `roles[].primary` | boolean | yes | One of: `true`. | | `roles[].type` | string | yes | One of: `base`. | | `roles[].value` | string | yes | | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `title` | string \| null | | The job title of the User. | | `userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | ## Response 204 No Content ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 404 Not Found ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Developer Agreement Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).