openapi: 3.0.2 info: description: 'This document describes the PagerDuty REST APIs. For guides and examples please visit our [Documentation.](https://developer.pagerduty.com/docs/get-started/getting-started/) Our REST APIs are defined in OpenAPI v3.x. You can view the schema at [github.com/PagerDuty/api-schema](https://github.com/PagerDuty/api-schema). Note that properties in some schemas have fields not shown by default such as `readOnly`, `format`, and `default`. Hover your cursor over the right column that looks like `optional+1` to see the full list of fields. ' contact: name: PagerDuty Support url: http://www.pagerduty.com/support email: support@pagerduty.com title: PagerDuty Abilities Alert Grouping Settings API version: 2.0.0 servers: - url: https://api.pagerduty.com description: PagerDuty V2 API. security: - api_key: [] tags: - name: Alert Grouping Settings description: 'Alert Grouping Settings allow you to configure how alerts in services are grouped together into incidents. ' paths: /alert_grouping_settings: description: List get: x-pd-requires-scope: services.read tags: - Alert Grouping Settings operationId: listAlertGroupingSettings description: '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` ' summary: PagerDuty List alert grouping settings parameters: - $ref: '#/components/parameters/header_Accept' - $ref: '#/components/parameters/header_Content-Type' - $ref: '#/components/parameters/offset_after' - $ref: '#/components/parameters/offset_before' - $ref: '#/components/parameters/offset_total' - $ref: '#/components/parameters/offset_limit' - $ref: '#/components/parameters/services' responses: '200': description: An array of alert grouping settings. content: application/json: schema: allOf: - type: object properties: alert_grouping_settings: type: array description: The list of alert grouping settings your account has. items: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_settings examples: response: summary: Response Example value: 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 '401': $ref: '#/components/responses/Unauthorized' post: x-pd-requires-scope: services.write tags: - Alert Grouping Settings operationId: postAlertGroupingSettings description: '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` ' summary: PagerDuty Create an Alert Grouping Setting parameters: - $ref: '#/components/parameters/header_Accept' - $ref: '#/components/parameters/header_Content-Type' requestBody: content: application/json: schema: type: object properties: alert_grouping_setting: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_setting examples: request: summary: Request Example value: 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 responses: '201': description: The new Alert Grouping Setting. content: application/json: schema: type: object properties: alert_grouping_setting: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_setting examples: response: summary: Response Example value: 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' '400': $ref: '#/components/responses/ArgumentError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /alert_grouping_settings/{id}: description: Retrieve, modify, or delete Alert Grouping Settings get: x-pd-requires-scope: services.read tags: - Alert Grouping Settings operationId: getAlertGroupingSetting description: '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` ' summary: PagerDuty Get an Alert Grouping Setting parameters: - $ref: '#/components/parameters/header_Accept' - $ref: '#/components/parameters/header_Content-Type' - $ref: '#/components/parameters/id' responses: '200': description: The Alert Grouping Setting. content: application/json: schema: type: object properties: alert_grouping_setting: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_setting examples: response: summary: Response Example value: 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' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: x-pd-requires-scope: services.write tags: - Alert Grouping Settings operationId: deleteAlertGroupingSetting description: '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` ' summary: PagerDuty Delete an Alert Grouping Setting parameters: - $ref: '#/components/parameters/header_Accept' - $ref: '#/components/parameters/header_Content-Type' - $ref: '#/components/parameters/id' responses: '204': description: The Alert Grouping Setting was deleted successfully. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: x-pd-requires-scope: services.write tags: - Alert Grouping Settings operationId: putAlertGroupingSetting description: '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` ' summary: PagerDuty Update an Alert Grouping Setting parameters: - $ref: '#/components/parameters/header_Accept' - $ref: '#/components/parameters/header_Content-Type' - $ref: '#/components/parameters/id' requestBody: content: application/json: schema: type: object properties: alert_grouping_setting: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_setting examples: request: summary: Request Example value: 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 responses: '200': description: The updated Alert Grouping Setting. content: application/json: schema: type: object properties: alert_grouping_setting: $ref: '#/components/schemas/AlertGroupingSetting' required: - alert_grouping_setting examples: response: summary: Response Example value: 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' '400': $ref: '#/components/responses/ArgumentError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: ContentBasedIntelligentAlertGroupingConfiguration: type: object title: Content and Intelligent Grouping description: The configuration for Content Based Intelligent Alert Grouping properties: aggregate: type: string description: 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. enum: - all, any fields: type: array description: 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. time_window: type: integer minimum: 300 maximum: 3600 description: 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. recommended_time_window: readOnly: true type: integer description: 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 customer`s to use this value, please set `time_window` to 0 to use the `recommended_time_window`. AlertGroupingSetting: type: object description: '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. ' properties: id: type: string readOnly: true name: type: string nullable: true description: 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. description: type: string nullable: true description: An optional description in string that provides more information about an AlertGroupingSetting object. type: type: string enum: - content_based - content_based_intelligent config: anyOf: - $ref: '#/components/schemas/ContentBasedAlertGroupingConfiguration' - $ref: '#/components/schemas/ContentBasedIntelligentAlertGroupingConfiguration' services: type: array description: 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. items: $ref: '#/components/schemas/ServiceReference' created_at: type: string format: date-time description: The ISO8601 date/time an AlertGroupingSetting got created at. readOnly: true updated_at: type: string format: date-time description: The ISO8601 date/time an AlertGroupingSetting last got updated at. readOnly: true Reference: allOf: - $ref: '#/components/schemas/Tag/allOf/0' - type: object required: - type - id ContentBasedAlertGroupingConfiguration: type: object title: Content Only Grouping description: The configuration for Content Based Alert Grouping properties: aggregate: type: string description: 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. enum: - all, any fields: type: array description: 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. time_window: type: integer minimum: 300 maximum: 86400 description: 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). recommended_time_window: readOnly: true type: integer description: 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 customer`s to use this value, please set `time_window` to 0 to use the `recommended_time_window`. ServiceReference: allOf: - $ref: '#/components/schemas/Reference' - type: object properties: type: type: string enum: - service_reference Tag: allOf: - type: object properties: id: type: string readOnly: true summary: type: string nullable: true readOnly: true description: A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. type: type: string readOnly: true description: 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. self: type: string nullable: true readOnly: true format: url description: the API show URL at which the object is accessible html_url: type: string nullable: true readOnly: true format: url description: a URL at which the entity is uniquely displayed in the Web app - type: object properties: type: type: string description: The type of object being created. default: tag enum: - tag label: type: string description: The label of the tag. maxLength: 191 required: - label - type example: type: tag label: Batman responses: NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/responses/Conflict/content/application~1json/schema' Unauthorized: description: 'Caller did not supply credentials or did not provide the correct credentials. If you are using an API key, it may be invalid or your Authorization header may be malformed. ' content: application/json: schema: $ref: '#/components/responses/Conflict/content/application~1json/schema' ArgumentError: description: Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work. content: application/json: schema: $ref: '#/components/responses/Conflict/content/application~1json/schema' Conflict: description: The request conflicts with the current state of the server. content: application/json: schema: type: object properties: error: type: object properties: code: type: integer readOnly: true message: type: string readOnly: true description: Error message string errors: type: array readOnly: true items: type: string readOnly: true description: Human-readable error details example: message: Not Found code: 2100 Forbidden: description: 'Caller is not authorized to view the requested resource. While your authentication is valid, the authenticated user or token does not have permission to perform this action. ' content: application/json: schema: $ref: '#/components/responses/Conflict/content/application~1json/schema' parameters: header_Accept: name: Accept description: The `Accept` header is used as a versioning header. in: header required: true schema: type: string default: application/vnd.pagerduty+json;version=2 header_Content-Type: name: Content-Type in: header required: true schema: type: string default: application/json enum: - application/json offset_after: name: after in: query required: false description: Cursor to retrieve next page; only present if next page exists. schema: type: string offset_before: name: before in: query required: false description: Cursor to retrieve previous page; only present if not on first page. schema: type: string id: name: id description: The ID of the resource. in: path required: true schema: type: string offset_total: name: total in: query required: false description: 'By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated. See our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information. ' schema: default: false type: boolean services: name: service_ids[] in: query description: An array of service IDs. Only results related to these services will be returned. explode: true schema: type: array items: type: string offset_limit: name: limit in: query required: false description: The number of results per page. schema: type: integer securitySchemes: api_key: type: apiKey name: Authorization in: header description: The API Key with format `Token token=`