PagerDuty Escalation Policies API

openapi: 3.2.0
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:
  responses:
    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
    TooManyRequests:
      description: Too many requests have been made, the rate limit has been reached.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    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'
    PaymentRequired:
      description: '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.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    InternalServerError:
      description: Internal Server Error the PagerDuty server experienced an error.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    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'
    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'
  parameters:
    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_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
    offset_offset:
      name: offset
      in: query
      required: false
      description: Offset to start pagination search results.
      schema:
        type: integer
    offset_limit:
      name: limit
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
    id:
      name: id
      description: The ID of the resource.
      in: path
      required: true
      schema:
        type: string
    query:
      name: query
      in: query
      description: Filters the result, showing only the records whose name matches the query.
      required: false
      schema:
        type: string
    header_Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
        enum:
        - application/json
    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
    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
    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
    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
    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
    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
    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
    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
    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
  schemas:
    EscalationTargetReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        description: The escalation target is the entity that will be assigned an incident upon escalation.
        properties:
          type:
            enum:
            - user
            - schedule
            - user_reference
            - schedule_reference
            type: string
    Tag:
      allOf:
      - type: object
        properties:
          id:
            type: string
            readOnly: true
          summary:
            type:
            - string
            - 'null'
            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
            - 'null'
            readOnly: true
            format: url
            description: the API show URL at which the object is accessible
          html_url:
            type:
            - string
            - 'null'
            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
    TeamReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - team_reference
    AuditRecord:
      type: object
      readOnly: true
      description: An Audit Trail record
      properties:
        id:
          type: string
        self:
          type:
          - string
          - 'null'
          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
          - 'null'
          description: Action executi

# --- 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