PagerDuty Escalation Policies 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 Escalation Policies API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Escalation Policies
  description: 'Escalation policies define which user should be alerted at which time.

    '
paths:
  /escalation_policies:
    description: List and create escalation policies.
    get:
      tags:
      - Escalation Policies
      x-pd-requires-scope: escalation_policies.read
      operationId: listEscalationPolicies
      description: 'List all of the existing escalation policies.


        Escalation policies define which user should be alerted at which time.


        For more information see the [API Concepts Document](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#escalation-policies)


        Scoped OAuth requires: `escalation_policies.read`

        '
      summary: PagerDuty List escalation policies
      parameters:
      - $ref: '#/components/parameters/offset_limit'
      - $ref: '#/components/parameters/offset_offset'
      - $ref: '#/components/parameters/offset_total'
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/user_ids_escalation_policies'
      - $ref: '#/components/parameters/team_ids'
      - $ref: '#/components/parameters/include_escalation_policy'
      - $ref: '#/components/parameters/sort_by_escalation_policy'
      responses:
        '200':
          description: A paginated array of escalation policy objects.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    escalation_policies:
                      type: array
                      items:
                        $ref: '#/components/schemas/EscalationPolicy'
                  required:
                  - escalation_policies
              examples:
                response:
                  summary: Response Example
                  value:
                    escalation_policies:
                    - id: PANZZEQ
                      type: escalation_policy
                      summary: Engineering Escalation Policy
                      on_call_handoff_notifications: if_has_services
                      self: https://api.pagerduty.com/escalation_policies/PANZZEQ
                      html_url: https://subdomain.pagerduty.com/escalation_policies/PANZZEQ
                      name: Engineering Escalation Policy
                      escalation_rules:
                      - id: PANZZEQ
                        escalation_delay_in_minutes: 30
                        targets:
                        - id: PEYSGVF
                          summary: PagerDuty Admin
                          type: user_reference
                          self: https://api.pagerduty.com/users/PEYSGVF
                          html_url: https://subdomain.pagerduty.com/users/PEYSGVF
                        - id: PI7DH85
                          summary: Daily Engineering Rotation
                          type: schedule_reference
                          self: https://api.pagerduty.com/schedules/PI7DH85
                          html_url: https://subdomain.pagerduty.com/schedules/PI7DH85
                      services:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      num_loops: 0
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                    limit: 25
                    offset: 0
                    more: false
                    total: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      tags:
      - Escalation Policies
      x-pd-requires-scope: escalation_policies.write
      operationId: createEscalationPolicy
      description: '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](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#escalation-policies)


        Scoped OAuth requires: `escalation_policies.write`

        '
      summary: PagerDuty Create an escalation policy
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/optional_from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                escalation_policy:
                  $ref: '#/components/schemas/EscalationPolicy'
              required:
              - escalation_policy
            examples:
              request:
                summary: Request Example
                value:
                  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.
        description: The escalation policy to be created.
      responses:
        '201':
          description: The escalation policy that was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalation_policy:
                    $ref: '#/components/schemas/EscalationPolicy'
                required:
                - escalation_policy
              examples:
                response:
                  summary: Response Example
                  value:
                    escalation_policy:
                      id: PT20YPA
                      type: escalation_policy
                      summary: 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
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /escalation_policies/{id}:
    description: Manage an escalation policy.
    get:
      tags:
      - Escalation Policies
      x-pd-requires-scope: escalation_policies.read
      operationId: getEscalationPolicy
      description: 'Get information about an existing escalation policy and its rules.


        Escalation policies define which user should be alerted at which time.


        For more information see the [API Concepts Document](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#escalation-policies)


        Scoped OAuth requires: `escalation_policies.read`

        '
      summary: PagerDuty Get an escalation policy
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/include_escalation_policy'
      responses:
        '200':
          description: The escalation policy object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalation_policy:
                    $ref: '#/components/schemas/EscalationPolicy'
                required:
                - escalation_policy
              examples:
                response:
                  summary: Response Example
                  value:
                    escalation_policy:
                      id: PT20YPA
                      type: escalation_policy
                      summary: Another Escalation Policy
                      on_call_handoff_notifications: if_has_services
                      self: https://api.pagerduty.com/escalation_policies/PT20YPA
                      html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      name: Another Escalation Policy
                      escalation_rules:
                      - id: PGHDV41
                        escalation_delay_in_minutes: 30
                        targets:
                        - id: PAM4FGS
                          summary: Kyler Kuhn
                          type: user_reference
                          self: https://api.pagerduty.com/users/PAM4FGS
                          html_url: https://subdomain.pagerduty.com/users/PAM4FGS
                        - id: PI7DH85
                          summary: Daily Engineering Rotation
                          type: schedule_reference
                          self: https://api.pagerduty.com/schedules/PI7DH85
                          html_url: https://subdomain.pagerduty.com/schedules/PI7DH85
                      services:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      num_loops: 2
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      description: This is yet another escalation policy
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Escalation Policies
      x-pd-requires-scope: escalation_policies.write
      operationId: deleteEscalationPolicy
      description: '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](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#escalation-policies)


        Scoped OAuth requires: `escalation_policies.write`

        '
      summary: PagerDuty Delete an escalation policy
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: The escalation policy was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      tags:
      - Escalation Policies
      x-pd-requires-scope: escalation_policies.write
      operationId: updateEscalationPolicy
      description: '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](../../api-reference/ZG9jOjI3NDc5Nzc-api-concepts#escalation-policies)


        Scoped OAuth requires: `escalation_policies.write`

        '
      summary: PagerDuty Update an escalation policy
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                escalation_policy:
                  $ref: '#/components/schemas/EscalationPolicy'
              required:
              - escalation_policy
            examples:
              request:
                summary: Request Example
                value:
                  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.
        description: The escalation policy to be updated.
      responses:
        '200':
          description: The escalation policy that was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  escalation_policy:
                    $ref: '#/components/schemas/EscalationPolicy'
                required:
                - escalation_policy
              examples:
                response:
                  summary: Response Example
                  value:
                    escalation_policy:
                      id: PT20YPA
                      type: escalation_policy
                      summary: Another Escalation Policy
                      on_call_handoff_notifications: if_has_services
                      self: https://api.pagerduty.com/escalation_policies/PT20YPA
                      html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      name: Another Escalation Policy
                      escalation_rules:
                      - id: PGHDV41
                        escalation_delay_in_minutes: 30
                        targets:
                        - id: PAM4FGS
                          summary: Kyler Kuhn
                          type: user_reference
                          self: https://api.pagerduty.com/users/PAM4FGS
                          html_url: https://subdomain.pagerduty.com/users/PAM4FGS
                        - id: PI7DH85
                          summary: Daily Engineering Rotation
                          type: schedule_reference
                          self: https://api.pagerduty.com/schedules/PI7DH85
                          html_url: https://subdomain.pagerduty.com/schedules/PI7DH85
                      services:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      num_loops: 2
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      description: This is yet another escalation policy
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /escalation_policies/{id}/audit/records:
    description: List audit records of changes made to the escalation policy.
    get:
      x-pd-requires-scope: audit_records.read
      tags:
      - Escalation Policies
      operationId: listEscalationPolicyAuditRecords
      summary: PagerDuty List audit records for an escalation policy
      description: 'The returned records are sorted by the `execution_time` from newest to oldest.


        See [`Cursor-based pagination`](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for instructions on how to paginate through the result set.


        For more information see the [Audit API Document](https://developer.pagerduty.com/docs/rest-api-v2/audit-records-api/).


        Scoped OAuth requires: `audit_records.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/cursor_limit'
      - $ref: '#/components/parameters/cursor_cursor'
      - $ref: '#/components/parameters/audit_since'
      - $ref: '#/components/parameters/audit_until'
      responses:
        '200':
          description: Records matching the query criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditRecordResponseSchema'
              examples:
                response:
                  $ref: '#/components/examples/AuditRecordEscalationPolicyResponse'
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    team_ids:
      name: team_ids[]
      in: query
      description: An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.
      explode: true
      schema:
        type: array
        items:
          type: string
        uniqueItems: true
    audit_since:
      name: since
      in: query
      description: The start of the date range over which you want to search. If not specified, defaults to `now() - 24 hours` (past 24 hours)
      schema:
        type: string
        format: date-time
    query:
      name: query
      in: query
      description: Filters the result, showing only the records whose name matches the query.
      required: false
      schema:
        type: string
    offset_offset:
      name: offset
      in: query
      required: false
      description: Offset to start pagination search results.
      schema:
        type: integer
    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
    audit_until:
      name: until
      in: query
      description: 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`.
      schema:
        type: string
        format: date-time
    audit_method_type:
      name: method_type
      in: query
      description: Method type filter.
      schema:
        type: string
        description: '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.

          '
        enum:
        - browser
        - oauth
        - api_token
        - identity_provider
        - other
    sort_by_escalation_policy:
      name: sort_by
      in: query
      description: Used to specify the field you wish to sort the results on.
      schema:
        type: string
        enum:
        - name
        - name:asc
        - name:desc
        default: name
    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
    optional_from_header:
      name: From
      in: header
      description: The email address of a valid user associated with the account making the request. This is optional, and is only used for change tracking.
      required: false
      schema:
        type: string
        format: email
    cursor_cursor:
      name: cursor
      in: query
      required: false
      description: '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.

        '
      schema:
        type: string
    offset_limit:
      name: limit
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
    cursor_limit:
      name: limit
      in: query
      required: false
      description: The minimum of the `limit` parameter used in the request or the maximum request size of the API.
      schema:
        type: integer
    user_ids_escalation_policies:
      name: user_ids[]
      in: query
      description: Filters the results, showing only escalation policies on which any of the users is a target.
      explode: true
      schema:
        type: array
        items:
          type: string
        uniqueItems: true
    include_escalation_policy:
      name: include[]
      in: query
      description: Array of additional Models to include in response.
      explode: true
      schema:
        type: string
        enum:
        - services
        - teams
        - targets
        uniqueItems: true
  schemas:
    EscalationRule:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        escalation_delay_in_minutes:
          type: integer
          description: The number of minutes before an unacknowledged incident escalates away from this rule.
        targets:
          type: array
          minItems: 1
          maxItems: 10
          description: The targets an incident should be assigned to upon reaching this rule.
          items:
            $ref: '#/components/schemas/EscalationTargetReference'
        escalation_rule_assignment_strategy:
          type: string
          description: The strategy used to assign the escalation rule to an incident.
          enum:
          - round_robin
          - assign_to_everyone
      required:
      - escalation_delay_in_minutes
      - targets
      example:
        escalation_delay_in_minutes: 30
        targets:
        - id: PAM4FGS
          type: user_reference
        - id: PI7DH85
          type: schedule_reference
    TeamReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - team_reference
    AuditMetadata:
      type: object
      properties:
        messages:
          type: array
          nullable: true
          items:
            type: string
            example: Message about the result
    CursorPagination:
      type: object
      properties:
        limit:
          type: integer
          description: The minimum of the `limit` parameter used in the request or the maximum request size of the API.
          readOnly: true
        next_cursor:
          type: string
          description: '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.

            '
          example: dXNlcjaVMzc5V0ZYTlo=
          nullable: true
          readOnly: true
      required:
      - limit
      - next_cursor
    AuditRecord:
      type: object
      readOnly: true
      description: An Audit Trail record
      properties:
        id:
          type: string
        self:
          type: string
          nullable: true
          description: Record URL.
        execution_time:
          type: string
          format: date-time
          description: The date/time the action executed, in ISO8601 format and millisecond precision.
        execution_context:
          type: object
          description: Action execution context
          properties:
            request_id:
              type: string
              nullable: true
              description: Request Id
            remote_address:
              type: string
              nullable: true
              description: remote address
          nullable: true
        actors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Reference'
        method:
          type: object
          description: The method information
          properties:
            description:
              type: string
              nullable: true
            truncated_token:
              description: Truncated token containing the last 4 chars of the token's actual value.
              type: string
              nullable: true
              example: 3xyz
            type:
              $ref: '#/components/parameters/audit_method_type/schema'
          required:
          - type
        root_resource:
          $ref: '#/components/schemas/Reference'
        action:
          type: string
          example: create
        details:
          type: object
          nullable: true
          description: 'Additional details to provide further information about the action or

            the resource that has been audited.

            '
          properties:
            resource:
              $ref: '#/components/schemas/Reference'
            fields:
              description: 'A set of fields that have been affected.

                The fields that have not been affected MAY be returned.

                '
              type: array
              nullable: true
              items:
                type: object
                description: "Information about the affected field.\nWhen available, field's before and after values are returned:\n  \n#### Resource creation\n- `value` MAY be returned\n\n#### Resource update\n- `value` MAY be returned\n- `before_value` MAY be returned\n\n#### Resource deletion\n- `before_value` MAY be returned\n"
                properties:
                  name:
                    type: string
                    description: Name of the resource field
                    example: name
                  description:
                    type: string
                    nullable: true
                    description: Human readable description of the resource field
                    example: First and Last name
                  value:
                    type: string
                    nullable: true
                    description: new or updated value of the field
                    example: Jonathan
                  before_value:
                    type: string
                    nullable: true
                    description: previous or deleted value of the field
                    example: John
                required:
                - name
            references:
              description: A set of references that have been affected.
              type: array
              nullable: true
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: Name of the reference

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pagerduty/refs/heads/main/openapi/pagerduty-escalation-policies-api-openapi.yml