PagerDuty Incidents 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 Incidents API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Incidents
  description: 'An incident represents a problem or an issue that needs to be addressed and resolved. Incidents trigger on a service, which prompts notifications to go out to on-call responders per the service''s escalation policy.

    '
paths:
  /incidents:
    description: List and update incidents.
    get:
      x-pd-requires-scope: incidents.read
      tags:
      - Incidents
      operationId: listIncidents
      description: 'List existing incidents.


        An incident represents a problem or an issue that needs to be addressed and resolved.


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


        Scoped OAuth requires: `incidents.read`

        '
      summary: PagerDuty List incidents
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/incident_list_limit'
      - $ref: '#/components/parameters/offset_offset'
      - $ref: '#/components/parameters/offset_total'
      - $ref: '#/components/parameters/date_range'
      - $ref: '#/components/parameters/incident_key'
      - $ref: '#/components/parameters/incident_services'
      - $ref: '#/components/parameters/team_ids'
      - $ref: '#/components/parameters/incident_assigned_to_user'
      - $ref: '#/components/parameters/incident_urgencies'
      - $ref: '#/components/parameters/time_zone'
      - $ref: '#/components/parameters/statuses_incidents'
      - $ref: '#/components/parameters/sort_by_incidents'
      - $ref: '#/components/parameters/include_incidents'
      - $ref: '#/components/parameters/since_incidents'
      - $ref: '#/components/parameters/until_incidents'
      responses:
        '200':
          description: A paginated array of incidents.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    incidents:
                      type: array
                      items:
                        $ref: '#/components/schemas/Incident'
                  required:
                  - incidents
              examples:
                response:
                  summary: Response Example
                  value:
                    incidents:
                    - id: PT4KHLK
                      type: incident
                      summary: '[#1234] The server is on fire.'
                      self: https://api.pagerduty.com/incidents/PT4KHLK
                      html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK
                      incident_number: 1234
                      title: The server is on fire.
                      created_at: '2015-10-06T21:30:42Z'
                      updated_at: '2015-10-06T21:40:23Z'
                      status: resolved
                      incident_key: baf7cf21b1da41b4b0221008339ff357
                      service:
                        id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      assignments: []
                      assigned_via: escalation_policy
                      last_status_change_at: '2015-10-06T21:38:23Z'
                      resolved_at: '2015-10-06T21:38:23Z'
                      first_trigger_log_entry:
                        id: Q02JTSNZWHSEKV
                        type: trigger_log_entry_reference
                        summary: Triggered through the API
                        self: https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK
                        html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV
                      alert_counts:
                        all: 2
                        triggered: 0
                        resolved: 2
                      is_mergeable: true
                      escalation_policy:
                        id: PT20YPA
                        type: escalation_policy_reference
                        summary: Another Escalation Policy
                        self: https://api.pagerduty.com/escalation_policies/PT20YPA
                        html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      pending_actions: []
                      acknowledgements: []
                      alert_grouping:
                        grouping_type: advanced
                        started_at: '2015-10-06T21:30:42Z'
                        ended_at: null
                        alert_grouping_active: true
                      last_status_change_by:
                        id: PXPGF42
                        type: user_reference
                        summary: Earline Greenholt
                        self: https://api.pagerduty.com/users/PXPGF42
                        html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      priority:
                        id: P53ZZH5
                        type: priority_reference
                        summary: P2
                        self: https://api.pagerduty.com/priorities/P53ZZH5
                      resolve_reason: null
                      conference_bridge:
                        conference_number: +1-415-555-1212,,,,1234#
                        conference_url: https://example.com/acb-123
                      incidents_responders: []
                      responder_requests: []
                      urgency: high
                    limit: 1
                    offset: 0
                    more: true
        '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'
    put:
      x-pd-requires-scope: incidents.write
      x-pd-operation-limit: true
      tags:
      - Incidents
      operationId: updateIncidents
      description: 'Acknowledge, resolve, escalate or reassign one or more incidents.


        An incident represents a problem or an issue that needs to be addressed and resolved.


        A maximum of 250 incidents may be updated at a time. If more than this number of incidents are given, the API will respond with status 413 (Request Entity Too Large).


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


        Scoped OAuth requires: `incidents.write`


        This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.

        '
      summary: PagerDuty Manage incidents
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/offset_limit'
      - $ref: '#/components/parameters/offset_offset'
      - $ref: '#/components/parameters/offset_total'
      - $ref: '#/components/parameters/from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                incidents:
                  type: array
                  description: An array of incidents, including the parameters to update.
                  items:
                    properties:
                      id:
                        type: string
                        description: The id of the incident to update.
                      type:
                        type: string
                        description: The incident type.
                        enum:
                        - incident
                        - incident_reference
                      status:
                        type: string
                        description: The new status of the incident.
                        enum:
                        - resolved
                        - acknowledged
                      resolution:
                        type: string
                        description: The resolution for this incident if status is set to resolved.
                      title:
                        type: string
                        description: A succinct description of the nature, symptoms, cause, or effect of the incident.
                      priority:
                        $ref: '#/components/schemas/PriorityReference'
                      escalation_level:
                        type: integer
                        description: Escalate the incident to this level in the escalation policy.
                      assignments:
                        type: array
                        description: Assign the incident to these assignees.
                        items:
                          properties:
                            assignee:
                              $ref: '#/components/schemas/UserReference'
                      escalation_policy:
                        $ref: '#/components/schemas/EscalationPolicyReference'
                      conference_bridge:
                        $ref: '#/components/schemas/ConferenceBridge'
                    required:
                    - id
                    - type
              required:
              - incidents
            examples:
              incidents:
                summary: Request Example
                value:
                  incidents:
                  - id: PT4KHLK
                    type: incident_reference
                    status: acknowledged
                  - id: PQMF62U
                    type: incident_reference
                    priority:
                      id: P53ZZH5
                      type: priority_reference
                  - id: PPVZH9X
                    type: incident_reference
                    status: resolved
                  - id: P8JOGX7
                    type: incident_reference
                    assignments:
                    - assignee:
                        id: PXPGF42
                        type: user_reference
      responses:
        '200':
          description: All of the updates succeeded.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    incidents:
                      type: array
                      items:
                        $ref: '#/components/schemas/Incident'
                  required:
                  - incidents
              examples:
                response:
                  summary: Response Example
                  value:
                    incidents:
                    - id: PT4KHLK
                      type: incident
                      summary: '[#1234] The server is on fire.'
                      self: https://api.pagerduty.com/incidents/PT4KHLK
                      html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK
                      incident_number: 1234
                      created_at: '2015-10-06T21:30:42Z'
                      updated_at: '2015-10-06T21:40:23Z'
                      status: resolved
                      title: The server is on fire.
                      alert_counts:
                        all: 2
                        triggered: 0
                        resolved: 2
                      pending_actions:
                      - type: unacknowledge
                        at: '2015-11-10T01:02:52Z'
                      - type: resolve
                        at: '2015-11-10T04:31:52Z'
                      incident_key: baf7cf21b1da41b4b0221008339ff357
                      service:
                        id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      assigned_via: escalation_policy
                      assignments:
                      - at: '2015-11-10T00:31:52Z'
                        assignee:
                          id: PXPGF42
                          type: user_reference
                          summary: Earline Greenholt
                          self: https://api.pagerduty.com/users/PXPGF42
                          html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      acknowledgements:
                      - at: '2015-11-10T00:32:52Z'
                        acknowledger:
                          id: PXPGF42
                          type: user_reference
                          summary: Earline Greenholt
                          self: https://api.pagerduty.com/users/PXPGF42
                          html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      resolved_at: '2015-10-06T21:38:23Z'
                      last_status_change_at: '2015-10-06T21:38:23Z'
                      last_status_change_by:
                        id: PXPGF42
                        type: user_reference
                        summary: Earline Greenholt
                        self: https://api.pagerduty.com/users/PXPGF42
                        html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      first_trigger_log_entry:
                        id: Q02JTSNZWHSEKV
                        type: trigger_log_entry_reference
                        summary: Triggered through the API
                        self: https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK
                        html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV
                      escalation_policy:
                        id: PT20YPA
                        type: escalation_policy_reference
                        summary: Another Escalation Policy
                        self: https://api.pagerduty.com/escalation_policies/PT20YPA
                        html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      urgency: high
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/RequestEntityTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      x-pd-requires-scope: incidents.write
      x-pd-operation-limit: true
      tags:
      - Incidents
      operationId: createIncident
      description: 'Create an incident synchronously without a corresponding event from a monitoring service.


        An incident represents a problem or an issue that needs to be addressed and resolved.


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


        Scoped OAuth requires: `incidents.write`


        This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.

        '
      summary: PagerDuty Create an Incident
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                incident:
                  type: object
                  description: Details of the incident to be created.
                  properties:
                    type:
                      type: string
                      enum:
                      - incident
                    title:
                      type: string
                      description: A succinct description of the nature, symptoms, cause, or effect of the incident.
                    service:
                      $ref: '#/components/schemas/ServiceReference'
                    priority:
                      $ref: '#/components/schemas/PriorityReference'
                    urgency:
                      type: string
                      description: The urgency of the incident
                      enum:
                      - high
                      - low
                    body:
                      $ref: '#/components/schemas/IncidentBody'
                    incident_key:
                      type: string
                      description: A string which identifies the incident. Sending subsequent requests referencing the same service and with the same incident_key will result in those requests being rejected if an open incident matches that incident_key.
                    assignments:
                      type: array
                      description: Assign the incident to these assignees. Cannot be specified if an escalation policy is given.
                      items:
                        properties:
                          assignee:
                            $ref: '#/components/schemas/UserReference'
                    escalation_policy:
                      $ref: '#/components/schemas/EscalationPolicyReference'
                    conference_bridge:
                      $ref: '#/components/schemas/ConferenceBridge'
                  required:
                  - type
                  - title
                  - service
              required:
              - incident
            examples:
              request:
                summary: Request Example
                value:
                  incident:
                    type: incident
                    title: The server is on fire.
                    service:
                      id: PWIXJZS
                      type: service_reference
                    priority:
                      id: P53ZZH5
                      type: priority_reference
                    urgency: high
                    incident_key: baf7cf21b1da41b4b0221008339ff357
                    body:
                      type: incident_body
                      details: A disk is getting full on this machine. You should investigate what is causing the disk to fill, and ensure that there is an automated process in place for ensuring data is rotated (eg. logs should have logrotate around them). If data is expected to stay on this disk forever, you should start planning to scale up to a larger disk.
                    escalation_policy:
                      id: PT20YPA
                      type: escalation_policy_reference
      responses:
        '201':
          description: The incident object created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident:
                    $ref: '#/components/schemas/Incident'
                required:
                - incident
              examples:
                response:
                  summary: Response Example
                  value:
                    incident:
                      id: PT4KHLK
                      type: incident
                      title: The server is on fire.
                      summary: '[#1234] The server is on fire.'
                      self: https://api.pagerduty.com/incidents/PT4KHLK
                      html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK
                      incident_number: 1234
                      created_at: '2015-10-06T21:30:42Z'
                      updated_at: '2015-10-06T21:40:23Z'
                      status: triggered
                      incident_key: baf7cf21b1da41b4b0221008339ff357
                      service:
                        id: PWIXJZS
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PWIXJZS
                        html_url: https://subdomain.pagerduty.com/service-directory/PWIXJZS
                      priority:
                        id: P53ZZH5
                        type: priority_reference
                        summary: P2
                        self: https://api.pagerduty.com/priorities/P53ZZH5
                      assigned_via: escalation_policy
                      assignments:
                      - at: '2015-11-10T00:31:52Z'
                        assignee:
                          id: PXPGF42
                          type: user_reference
                          summary: Earline Greenholt
                          self: https://api.pagerduty.com/users/PXPGF42
                          html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      resolved_at: null
                      last_status_change_at: '2015-10-06T21:38:23Z'
                      last_status_change_by:
                        id: PXPGF42
                        type: user_reference
                        summary: Earline Greenholt
                        self: https://api.pagerduty.com/users/PXPGF42
                        html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      first_trigger_log_entry:
                        id: Q02JTSNZWHSEKV
                        type: trigger_log_entry_reference
                        summary: Triggered through the API
                        self: https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK
                        html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV
                      escalation_policy:
                        id: PT20YPA
                        type: escalation_policy_reference
                        summary: Another Escalation Policy
                        self: https://api.pagerduty.com/escalation_policies/PT20YPA
                        html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      urgency: high
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /incidents/{id}:
    description: Get an incident.
    get:
      x-pd-requires-scope: incidents.read
      tags:
      - Incidents
      operationId: getIncident
      description: 'Show detailed information about an incident. Accepts either an incident id, or an incident number.


        An incident represents a problem or an issue that needs to be addressed and resolved.


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


        Scoped OAuth requires: `incidents.read`

        '
      summary: PagerDuty Get an incident
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/include_incident'
      responses:
        '200':
          description: The incident requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident:
                    $ref: '#/components/schemas/Incident'
                required:
                - incident
              examples:
                response:
                  summary: Response Example
                  value:
                    incident:
                      id: PT4KHLK
                      type: incident
                      summary: '[#1234] The server is on fire.'
                      self: https://api.pagerduty.com/incidents/PT4KHLK
                      html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK
                      incident_number: 1234
                      title: The server is on fire.
                      created_at: '2015-10-06T21:30:42Z'
                      updated_at: '2015-10-06T21:40:23Z'
                      status: acknowledged
                      incident_key: baf7cf21b1da41b4b0221008339ff357
                      service:
                        id: PIJ90N7
                        type: service_reference
                        summary: My Mail Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      assignments:
                      - at: '2015-11-10T00:31:52Z'
                        assignee:
                          id: PXPGF42
                          type: user_reference
                          summary: Earline Greenholt
                          self: https://api.pagerduty.com/users/PXPGF42
                          html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      assigned_via: escalation_policy
                      last_status_change_at: '2015-10-06T21:38:23Z'
                      resolved_at: null
                      first_trigger_log_entry:
                        id: Q02JTSNZWHSEKV
                        type: trigger_log_entry_reference
                        summary: Triggered through the API
                        self: https://api.pagerduty.com/log_entries/Q02JTSNZWHSEKV?incident_id=PT4KHLK
                        html_url: https://subdomain.pagerduty.com/incidents/PT4KHLK/log_entries/Q02JTSNZWHSEKV
                      alert_counts:
                        all: 2
                        triggered: 1
                        resolved: 1
                      is_mergeable: true
                      escalation_policy:
                        id: PT20YPA
                        type: escalation_policy_reference
                        summary: Another Escalation Policy
                        self: https://api.pagerduty.com/escalation_policies/PT20YPA
                        html_url: https://subdomain.pagerduty.com/escalation_policies/PT20YPA
                      teams:
                      - id: PQ9K7I8
                        type: team_reference
                        summary: Engineering
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                        html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
                      pending_actions:
                      - type: unacknowledge
                        at: '2015-11-10T01:02:52Z'
                      - type: resolve
                        at: '2015-11-10T04:31:52Z'
                      acknowledgements:
                      - at: '2015-11-10T00:32:52Z'
                        acknowledger:
                          id: PXPGF42
                          type: user_reference
                          summary: Earline Greenholt
                          self: https://api.pagerduty.com/users/PXPGF42
                          html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      alert_grouping:
                        grouping_type: advanced
                        started_at: '2015-10-06T21:30:42Z'
                        ended_at: null
                        alert_grouping_active: true
                      last_status_change_by:
                        id: PXPGF42
                        type: user_reference
                        summary: Earline Greenholt
                        self: https://api.pagerduty.com/users/PXPGF42
                        html_url: https://subdomain.pagerduty.com/users/PXPGF42
                      priority:
                        id: P53ZZH5
                        type: priority_reference
                        summary: P2
                        self: https://api.pagerduty.com/priorities/P53ZZH5
                      resolve_reason: null
                      conference_bridge:
                        conference_number: +1-415-555-1212,,,,1234#
                        conference_url: https://example.com/acb-123
                      incidents_responders:
                      - state: pending
                        user:
                          id: PL7A2O4
                          type: user_reference
                          summary: Lee Turner
                          self: https://api.pagerduty.com/users/PL7A2O4
                          html_url: https://subdomain.pagerduty.com/users/PL7A2O4
                          avatar_url: https://secure.gravatar.com/avatar/51c673f51f6b483b24c889bbafbd2a67.png?d=mm&r=PG
                        incident:
                          id: PXP12GZ
                          type: incident_reference
                          summary: Ongoing Incident in Mailroom
                          self: https://api.pagerduty.com/incidents/PXP12GZ
                          html_url: https://subdomain.pagerduty.com/incidents/PXP12GZ
                        updated_at: '2018-08-09T14:40:48-07:00'
                        message: Please help with issue - join bridge at +1(234)-567-8910
                        requester:
                          id: P09TT3C
                          type: user_reference
                          summary: Jane Doe
                          self: https://api.pagerduty.com/users/P09TT3C
                          html_url: https://subdomain.pagerduty.com/users/P09TT3C
                          avatar_url: https://secure.gravatar.com/avatar/1c747247b75acc1f724e2784c838b3f8.png?d=mm&r=PG
                        requested_at: '2018-08-09T21:40:49Z'
                      responder_requests:
                      - incident:
                          id: PXP12GZ
                          type: incident_reference
                          summary: Ongoing Incident in Mailroom
                          self: https://api.pagerduty.com/incidents/PXP12GZ
                          html_url: https://subdomain.pagerduty.com/incidents/PXP12GZ
                        requester:
                          id: P09TT3C
                          type: user_reference
                          summary: Jane Doe
                          self: https://api.pagerduty.com/users/P09TT3C
                          html_url: https://subdomain.pagerduty.com/users/P09TT3C
                        requested_a

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