PagerDuty Alert Grouping Settings API

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=<API_KEY>`