PagerDuty Extensions 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 Extensions API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Extensions
  description: 'Extensions are representations of Extension Schema objects that are attached to Services.

    '
paths:
  /extensions:
    description: List and create extensions.
    get:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.read
      operationId: listExtensions
      description: 'List existing extensions.


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.read`

        '
      summary: PagerDuty List extensions
      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/extension_object_id'
      - $ref: '#/components/parameters/extension_schema_id'
      - $ref: '#/components/parameters/include_extensions'
      responses:
        '200':
          description: A paginated array of extensions.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    extensions:
                      type: array
                      items:
                        $ref: '#/components/schemas/Extension'
                  required:
                  - extensions
              examples:
                response:
                  summary: Response Example
                  value:
                    extensions:
                    - id: PPGPXHO
                      self: https://api.pagerduty.com/extensions/PPGPXHO
                      endpoint_url: https://example.com/receive_a_pagerduty_webhook
                      name: My Webhook
                      summary: My Webhook
                      type: extension
                      extension_schema:
                        id: PJFWPEP
                        type: extension_schema_reference
                        summary: Generic Webhook
                        self: https://api.pagerduty.com/extension_schemas/PJFWPEP
                      extension_objects:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Application Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                    limit: 25
                    offset: 0
                    more: false
                    total: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.write
      operationId: createExtension
      description: 'Create a new Extension.


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.write`

        '
      summary: PagerDuty Create an extension
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                extension:
                  $ref: '#/components/schemas/Extension'
              required:
              - extension
            examples:
              request:
                summary: Request Example
                value:
                  extension:
                    endpoint_url: https://example.com/receive_a_pagerduty_webhook
                    name: My Webhook
                    extension_schema:
                      id: PJFWPEP
                      type: extension_schema_reference
                    extension_objects:
                    - id: PIJ90N7
                      type: service_reference
              requestCustomHeaders:
                summary: Request Example with Custom Headers
                value:
                  extension:
                    endpoint_url: https://example.com/receive_a_pagerduty_webhook
                    name: My Webhook
                    extension_schema:
                      id: PJFWPEP
                      type: extension_schema_reference
                    extension_objects:
                    - id: PIJ90N7
                      type: service_reference
                    config:
                      headers:
                      - name: Authorization
                        value: Token token=super_secret_token_value
        description: The extension to be created
      responses:
        '201':
          description: The extension that was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    $ref: '#/components/schemas/Extension'
                required:
                - extension
              examples:
                response:
                  summary: Response Example
                  value:
                    extension:
                      id: PPGPXHO
                      self: https://api.pagerduty.com/extensions/PPGPXHO
                      endpoint_url: https://example.com/receive_a_pagerduty_webhook
                      name: My Webhook
                      summary: My Webhook
                      type: extension
                      extension_schema:
                        id: PJFWPEP
                        type: extension_schema_reference
                        summary: Generic Webhook
                        self: https://api.pagerduty.com/extension_schemas/PJFWPEP
                      extension_objects:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Application Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
      callbacks:
        webhookV2:
          endpoint_url:
            post:
              parameters: []
              tags:
              - Webhooks V2
              operationId: webhookV2
              description: Receive webhook indicating incident state has changed.
              summary: Receive webhook
              security: []
              responses:
                '200':
                  description: Your server implementation should return this if it successfuly received the webhook.
              requestBody:
                description: Webhook.
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        messages:
                          type: array
                          description: An array of webhook messages.
                          items:
                            $ref: '#/components/schemas/WebhookIncidentAction'
        webhookV1:
          endpoint_url:
            post:
              parameters: []
              tags:
              - Webhooks V1
              operationId: webhookV1
              description: Receive webhook indicating incident state has changed.
              summary: Receive webhook
              security: []
              responses:
                '200':
                  description: Your server implementation should return this if it successfuly received the webhook.
              requestBody:
                description: Webhook.
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/WebhooksV1Message'
  /extensions/{id}:
    description: Manage an extension.
    get:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.read
      operationId: getExtension
      description: 'Get details about an existing extension.


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.read`

        '
      summary: PagerDuty Get an extension
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/include_extensions_id'
      responses:
        '200':
          description: The extension that was requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    $ref: '#/components/schemas/Extension'
                required:
                - extension
              examples:
                response:
                  summary: Response Example
                  value:
                    extension:
                      id: PPGPXHO
                      self: https://api.pagerduty.com/extensions/PPGPXHO
                      endpoint_url: https://example.com/receive_a_pagerduty_webhook
                      name: My Webhook
                      summary: My Webhook
                      type: extension
                      extension_schema:
                        id: PJFWPEP
                        type: extension_schema_reference
                        summary: Generic Webhook
                        self: https://api.pagerduty.com/extension_schemas/PJFWPEP
                      extension_objects:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Application Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      temporarily_disabled: false
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.write
      operationId: deleteExtension
      description: 'Delete an existing extension.


        Once the extension is deleted, it will not be accessible from the web UI and new incidents won''t be able to be created for this extension.


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.write`

        '
      summary: PagerDuty Delete an extension
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: The extension was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.write
      operationId: updateExtension
      description: 'Update an existing extension.


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.write`

        '
      summary: PagerDuty Update an extension
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                extension:
                  $ref: '#/components/schemas/Extension'
              required:
              - extension
            examples:
              request:
                summary: Request Example
                value:
                  extension:
                    endpoint_url: https://example.com/receive_a_pagerduty_webhook
                    name: My Webhook
                    extension_schema:
                      id: PJFWPEP
                      type: extension_schema_reference
                    extension_objects:
                    - id: PIJ90N7
                      type: service_reference
              requestCustomHeaders:
                summary: Request Example with Custom Headers
                value:
                  extension:
                    endpoint_url: https://example.com/receive_a_pagerduty_webhook
                    name: My Webhook
                    extension_schema:
                      id: PJFWPEP
                      type: extension_schema_reference
                    extension_objects:
                    - id: PIJ90N7
                      type: service_reference
                    config:
                      headers:
                      - name: Authorization
                        value: Token token=super_secret_token_value
        description: The extension to be updated.
      responses:
        '200':
          description: The extension that was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    $ref: '#/components/schemas/Extension'
                required:
                - extension
              examples:
                response:
                  summary: Response Example
                  value:
                    extension:
                      id: PPGPXHO
                      self: https://api.pagerduty.com/extensions/PPGPXHO
                      endpoint_url: https://example.com/receive_a_pagerduty_webhook
                      name: My Webhook
                      summary: My Webhook
                      type: extension
                      extension_schema:
                        id: PJFWPEP
                        type: extension_schema_reference
                        summary: Generic Webhook
                        self: https://api.pagerduty.com/extension_schemas/PJFWPEP
                      extension_objects:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Application Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /extensions/{id}/enable:
    description: Enable an extension.
    post:
      tags:
      - Extensions
      x-pd-requires-scope: extensions.write
      operationId: enableExtension
      description: 'Enable an extension that is temporarily disabled. (This API does not require a request body.)


        Extensions are representations of Extension Schema objects that are attached to Services.


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


        Scoped OAuth requires: `extensions.write`

        '
      summary: PagerDuty Enable an extension
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The extension that was successfully enabled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    $ref: '#/components/schemas/Extension'
                required:
                - extension
              examples:
                response:
                  summary: Response Example
                  value:
                    extension:
                      id: PPGPXHO
                      self: https://api.pagerduty.com/extensions/PPGPXHO
                      endpoint_url: https://example.com/receive_a_pagerduty_webhook
                      name: My Webhook
                      summary: My Webhook
                      type: extension
                      extension_schema:
                        id: PJFWPEP
                        type: extension_schema_reference
                        summary: Generic Webhook
                        self: https://api.pagerduty.com/extension_schemas/PJFWPEP
                      extension_objects:
                      - id: PIJ90N7
                        type: service_reference
                        summary: My Application Service
                        self: https://api.pagerduty.com/services/PIJ90N7
                        html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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
    OutboundIntegrationReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - outbound_integration_reference
    NotifyLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          created_at:
            type: string
            format: date-time
            readOnly: true
            description: Time at which the log entry was created
          user:
            $ref: '#/components/schemas/UserReference'
          type:
            type: string
            enum:
            - notify_log_entry
    ResolveLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          type:
            type: string
            enum:
            - resolve_log_entry
    Notification:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        type:
          type: string
          description: The type of notification.
          enum:
          - sms_notification
          - email_notification
          - phone_notification
          - push_notification
          readOnly: true
        started_at:
          type: string
          format: date-time
          description: The time at which the notification was sent
          readOnly: true
        address:
          type: string
          description: The address where the notification was sent. This will be null for notification type `push_notification`.
          readOnly: true
        user:
          $ref: '#/components/schemas/UserReference'
        conferenceAddress:
          type: string
          description: The address of the conference bridge
        status:
          type: string
        ? ''
        : type: string
    Context:
      type: object
      discriminator:
        propertyName: type
      properties:
        type:
          type: string
          description: The type of context being attached to the incident.
          enum:
          - link
          - image
        href:
          type: string
          description: The link's target url
        src:
          type: string
          description: The image's source url
        text:
          type: string
          description: The alternate display for an image
      required:
      - type
    ReachTriggerLimitLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          type:
            type: string
            enum:
            - reach_trigger_limit_log_entry
    IncidentReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - incident_reference
    ExtensionSchemaReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - extension_schema_reference
    Team:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        properties:
          type:
            type: string
            description: The type of object being created.
            default: team
            enum:
            - team
          name:
            type: string
            description: The name of the team.
            maxLength: 100
          description:
            type: string
            description: The description of the team.
            maxLength: 1024
          default_role:
            type: string
            description: The team is private if the value is "none", or public if it is "manager" (the default permissions for a non-member of the team are either "none", or their base role up until "manager").
            default: manager
            enum:
            - manager
            - none
        required:
        - name
        - type
        example:
          type: team
          name: Engineering
          description: The engineering team
    Priority:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        properties:
          name:
            type: string
            description: The user-provided short name of the priority.
          description:
            type: string
            description: The user-provided description of the priority.
    Service:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        properties:
          type:
            type: string
            description: The type of object being created.
            default: service
            enum:
            - service
          name:
            type: string
            description: The name of the service.
          description:
            type: string
            description: The user-provided description of the service.
          auto_resolve_timeout:
            type: integer
            description: Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature.
            default: 14400
          acknowledgement_timeout:
            type: integer
            description: Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature.
            default: 1800
          created_at:
            type: string
            format: date-time
            description: The date/time when this service was created
            readOnly: true
          status:
            type: string
            description: 'The current state of the Service. Valid statuses are:



              - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with.

              - `warning`: The service is enabled and has one or more acknowledged incidents.

              - `critical`: The service is enabled and has one or more triggered incidents.

              - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode.

              - `disabled`: The service is disabled and will not have any new triggered incidents.

              '
            enum:
            - active
            - warning
            - critical
            - maintenance
            - disabled
            default: active
          last_incident_timestamp:
            type: string
            format: date-time
            description: The date/time when the most recent incident was created for this service.
            readOnly: true
          escalation_policy:
            $ref: '#/components/schemas/EscalationPolicyReference'
          response_play:
            deprecated: true
            description: Response plays associated with this service.
            allOf:
            - $ref: '#/components/schemas/Reference'
            - type: object
              properties:
                type:
                  type: string
                  enum:
                  - response_play_reference
          teams:
            type: array
            description: The set of teams associated with this service.
            items:
              $ref: '#/components/schemas/TeamReference'
            readOnly: true
          integrations:
            type: array
            description: An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references.
            items:
              $ref: '#/components/schemas/IntegrationReference'
            readOnly: true
          incident_urgency_rule:
            $ref: '#/components/schemas/IncidentUrgencyRule'
          support_hours:
            $ref: '#/components/schemas/SupportHours'
          scheduled_actions:
            type: array
            description: An array containing scheduled actions for the service.
            items:
              $ref: '#/components/schemas/ScheduledAction'
          addons:
            type: array
            description: The array of Add-ons associated with this service.
            items:
              $ref: '#/components/schemas/AddonReference'
            readOnly: true
          alert_creation:
            type: string
            deprecated: true
            description: 'Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging.

              * "create_incidents" - The service will create one incident and zero alerts for each incoming event.

              * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event.

              This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service.

              '
            enum:
            - create_incidents
            - create_alerts_and_incidents
            default: create_alerts_and_incidents
          alert_grouping_parameters:
            $ref: '#/components/schemas/AlertGroupingParameters'
          alert_grouping:
            type: string
            deprecated: true
            description: 'Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options:

              * null - No alert grouping on the service. Each alert will create a separate incident;

              * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans;

              * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans

              '
            enum:
            - time
            - intelligent
          alert_grouping_timeout:
            type: integer
            deprecated: true
            description: 'The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`.

              '
          auto_pause_notifications_parameters:
            $ref: '#/components/schemas/AutoPauseNotificationsParameters'
        required:
        - type
        - escalation_policy
        example:
          id: PSI2I2O
          summary: string
          type: service
          self: string
          html_url: string
          name: My Web App
          description: My cool web application that does things.
          auto_resolve_timeout: 14400
          acknowledgement_timeout: 600
          status: active
          escalation_policy:
            id: PWIP6CQ
            type: escalation_policy_reference
          response_play:
            id: 1677af3c-44cf-50f4-6c68-818f7f514802
            type: response_play_reference
          incident_urgency_rule:
            type: use_support_hours
            during_support_hours:
              type: constant
              urgency: high
            outside_support_hours:
              type: constant
              urgency: low
          support_hours:
            type: fixed_time_per_day
            time_zone: America/Lima
            start_time: 09:00:00
            end_time: '17:00:00'
  

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