PagerDuty Extensions 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 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:
    ResponderRequest:
      type: object
      properties:
        incident:
          $ref: '#/components/schemas/IncidentReference'
        requester:
          $ref: '#/components/schemas/UserReference'
        requested_at:
          type: string
          description: The time the request was made
        message:
          type: string
          description: The message sent with the responder request
        responder_request_targets:
          type: array
          description: The array of targets the responder request is being sent to
          items:
            $ref: '#/components/schemas/ResponderRequestTargetReference'
    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
    TeamReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - team_reference
    AcknowledgerReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - description: The acknowledger represents the entity that made the acknowledgement for an incident.
        type: object
        properties:
          type:
            enum:
            - user_reference
            - service_reference
            type: string
    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.
    User:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        properties:
          name:
            type: string
            description: The name of the user.
            maxLength: 100
          type:
            type: string
            description: The type of object being created.
            default: user
            enum:
            - user
          email:
            type: string
            format: email
            description: The user's email address.
            minLength: 6
            maxLength: 100
          time_zone:
            type: string
            format: tzinfo
            description: The preferred time zone name. If null, the account's time zone will be used.
          color:
            type: string
            description: The schedule color.
          role:
            description: The user role. Account must have the `read_only_users` ability to set a user as a `read_only_user` or a `read_only_limited_user`, and must have advanced permissions abilities to set a user as `observer` or `restricted_access`.
            type: string
            enum:
            - admin
            - limited_user
            - observer
            - owner
            - read_only_user
            - restricted_access
            - read_only_limited_user
            - user
          avatar_url:
            type: string
            format: url
            description: The URL of the user's avatar.
            readOnly: true
          description:
            type:
            - string
            - 'null'
            description: The user's bio.
          invitation_sent:
            type: boolean
            readOnly: true
            description: If true, the user has an outstanding invitation.
          job_title:
            type: string
            description: The user's title.
            maxLength: 100
          teams:
            type: array
            readOnly: true
            description: The list of teams to which the user belongs. Account must have the `teams` ability to set this.
            items:
              $ref: '#/components/schemas/TeamReference'
          contact_methods:
            type: array
            readOnly: true
            description: The list of contact methods for the user.
            items:
              $ref: '#/components/schemas/ContactMethodReference'
          notification_rules:
            readOnly: true
            type: array
            description: The list of notification rules for the user.
            items:
              $ref: '#/components/schemas/NotificationRuleReference'
        required:
        - name
        - email
        - type
        example:
          type: user
          name: Earline Greenholt
          email: 125.greenholt.earline@graham.name
          time_zone: America/Lima
          color: green
          role: admin
          job_title: Director of Engineering
          avatar_url: https://secure.gravatar.com/avatar/1d1a39d4635208d5664082a6c654a73f.png?d=mm&r=PG
          description: I'm the boss
    UrgencyChangeLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          type:
            type: string
            enum:
            - urgency_change_log_entry
    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
    ScheduledAction:
      type: object
      properties:
        type:
          type: string
          description: The type of schedule action. Must be set to urgency_change.
          enum:
          - urgency_change
        at:
          type: object
          description: Represents when scheduled action will occur.
          properties:
            type:
              type: string
              description: Must be set to named_time.
              enum:
              - named_time
            name:
              type: string
              description: Designates either the start or the end of support hours.
              enum:
              - support_hours_start
              - support_hours_end
          required:
          - type
          - name
        to_urgency:
          type: string
          description: Urgency level. Must be set to high.
          enum:
          - high
      required:
      - type
      - at
      - to_urgency
    FlexibleTimeWindowIntelligentAlertGroupingConfig:
      type: object
      title: Intelligent Alert Grouping
      description: The configuration for Intelligent Alert Grouping. Note that this configuration is only available for certain plans.
      properties:
        time_window:
          type: integer
          minimum: 300
          maximum: 3600
          description: The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600.
        recommended_time_window:
          readOnly: true
          type: integer
          description: In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service`s average Alert inter-arrival time. We encourage customer`s to use this value, please set `time_window` to 0 to use the `recommended_time_window`.
    RepeatEscalationPathLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          type:
            type: string
            enum:
            - repeat_escalation_path_log_entry
    AddonReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          src:
            type: string
            format: url
            description: The URL source of the Addon
          name:
            type: string
            description: The user entered name of the Addon.
          type:
            type: string
            enum:
            - full_page_addon_reference
            - incident_show_addon_reference
    SnoozeLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          changed_actions:
            type: array
            items:
              $ref: '#/components/schemas/IncidentAction'
          type:
            type: string
            enum:
            - snooze_log_entry
    WebhooksV1AssignedToUser:
      type: object
      description: The user assigned to the incident.
      readOnly: true
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
          description: The user's name.
          readOnly: true
        email:
          type: string
          format: email
          description: The user's email address.
          readOnly: true
        html_url:
          type: string
          format: url
          readOnly: true
    IncidentAction:
      description: An incident action is a pending change to an incident that will automatically happen at some future time.
      type: object
      properties:
        type:
          type: string
          enum:
          - unacknowledge
          - escalate
          - resolve
          - urgency_change
        at:
          type: string
          format: date-time
        to:
          description: The urgency that the incident will change to. This field is only present when the type is `urgency_change`.
          type: string
          enum:
          - high
      discriminator:
        propertyName: type
      required:
      - type
      - at
    ExhaustEscalationPathLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          type:
            type: string
            enum:
            - exhaust_escalation_path_log_entry
    AcknowledgeLogEntry:
      allOf:
      - $ref: '#/components/schemas/LogEntry'
      - type: object
        properties:
          acknowledgement_timeout:
            type: integer
            description: Duration for which the acknowledgement lasts, in seconds. Services can contain an `acknowledgement_timeout` property, which specifies the length of time acknowledgements should last for. Each time an incident is acknowledged, this timeout is copied into the acknowledgement log entry. This property is optional, as older log entries may not contain it. It may also be `null`, as acknowledgements can be performed on incidents whose services have no `acknowledgement_timeout` set.
          type:
            type: string
            enum:
            - acknowledgement_log_entry
    EscalationPolicyReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - escalation_policy_reference
    ContactMethodReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - email_contact_method_reference
            - phone_contact_method_reference
            - push_notification_contact_method_reference
            - sms_contact_method_reference
    AlertGroupingParameters:
      type: object
      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. To turn grouping off set the type to null.

        '
      properties:
        type:
          type:
          - string
          - 'null'
          enum:
          - time
          - intelligent
          - content_based
          - null
        config:
          anyOf:
          - $ref: '#/components/schemas/FlexibleTimeWindowIntelligentAlertGroupingConfig'
          - $ref: '#/components/schemas/TimeBasedAlertGroupingConfiguration'
          - $ref: '#/components/schemas/ContentBasedAlertGroupingConfiguration'
    NotificationRuleReference:
    

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