PagerDuty Services 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 Services API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Services
paths:
  /services:
    description: List and create services.
    get:
      tags:
      - Services
      operationId: listServices
      x-pd-requires-scope: services.read
      description: 'List existing Services.


        A service may represent an application, component, or team you wish to open incidents against.


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


        Scoped OAuth requires: `services.read`

        '
      summary: PagerDuty List services
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/offset_limit'
      - $ref: '#/components/parameters/offset_offset'
      - $ref: '#/components/parameters/offset_total'
      - $ref: '#/components/parameters/team_ids'
      - $ref: '#/components/parameters/time_zone'
      - $ref: '#/components/parameters/sort_by_service'
      - $ref: '#/components/parameters/include_services'
      - $ref: '#/components/parameters/service_name'
      responses:
        '200':
          description: A paginated array of services.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    services:
                      type: array
                      items:
                        $ref: '#/components/schemas/Service'
                  required:
                  - services
              examples:
                response:
                  summary: Response Example
                  value:
                    services:
                    - id: PIJ90N7
                      summary: My Application Service
                      type: service
                      self: https://api.pagerduty.com/services/PIJ90N7
                      html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      name: My Application Service
                      auto_resolve_timeout: 14400
                      acknowledgement_timeout: 600
                      created_at: '2015-11-06T11:12:51-05:00'
                      status: active
                      alert_creation: create_alerts_and_incidents
                      alert_grouping_parameters:
                        type: intelligent
                      integrations:
                      - id: PQ12345
                        type: generic_email_inbound_integration_reference
                        summary: Email Integration
                        self: https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                        html_url: https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                      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
                      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'
                        days_of_week:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      scheduled_actions:
                      - type: urgency_change
                        at:
                          type: named_time
                          name: support_hours_start
                        to_urgency: high
                      auto_pause_notifications_parameters:
                        enabled: true
                        timeout: 300
                    limit: 25
                    offset: 0
                    more: false
                    total: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      x-pd-requires-scope: services.write
      tags:
      - Services
      operationId: createService
      description: 'Create a new service.


        If `status` is included in the request, it must have a value of `active` when creating a new service. If a different status is required, make a second request to update the service.


        A service may represent an application, component, or team you wish to open incidents against.


        There is a limit of 25,000 services per account. If the limit is reached, the API will respond with an error. There is also a limit of 100,000 open Incidents per Service. If the limit is reached and `auto_resolve_timeout` is disabled (set to 0 or null), the `auto_resolve_timeout` property will automatically be set to  84600 (1 day).


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Create a service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service:
                  $ref: '#/components/schemas/Service'
              required:
              - service
            examples:
              request:
                summary: Request Example
                value:
                  service:
                    type: service
                    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
                    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'
                      days_of_week:
                      - 1
                      - 2
                      - 3
                      - 4
                      - 5
                    scheduled_actions:
                    - type: urgency_change
                      at:
                        type: named_time
                        name: support_hours_start
                      to_urgency: high
                    alert_creation: create_alerts_and_incidents
                    alert_grouping_parameters:
                      type: time
                      config:
                        timeout: 2
                    auto_pause_notifications_parameters:
                      enabled: true
                      timeout: 300
        description: The service to be created
      responses:
        '201':
          description: The service that was created
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    $ref: '#/components/schemas/Service'
                required:
                - service
              examples:
                response:
                  summary: Response Example
                  value:
                    service:
                      id: PIJ90N7
                      summary: My Application Service
                      type: service
                      self: https://api.pagerduty.com/services/PIJ90N7
                      html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      name: My Application Service
                      auto_resolve_timeout: 14400
                      acknowledgement_timeout: 600
                      created_at: '2015-11-06T11:12:51-05:00'
                      status: active
                      alert_creation: create_alerts_and_incidents
                      integrations:
                      - id: PQ12345
                        type: generic_email_inbound_integration_reference
                        summary: Email Integration
                        self: https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                        html_url: https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                      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
                      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'
                        days_of_week:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      scheduled_actions:
                      - type: urgency_change
                        at:
                          type: named_time
                          name: support_hours_start
                        to_urgency: high
                      auto_pause_notifications_parameters:
                        enabled: true
                        timeout: 300
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
  /services/{id}:
    description: Manage a service.
    get:
      tags:
      - Services
      operationId: getService
      x-pd-requires-scope: services.read
      description: 'Get details about an existing service.


        A service may represent an application, component, or team you wish to open incidents against.


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


        Scoped OAuth requires: `services.read`

        '
      summary: PagerDuty Get a service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/include_services_id'
      responses:
        '200':
          description: The service requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    $ref: '#/components/schemas/Service'
                required:
                - service
              examples:
                response:
                  summary: Response Example
                  value:
                    service:
                      id: PIJ90N7
                      type: service
                      summary: My Application Service
                      self: https://api.pagerduty.com/services/PIJ90N7
                      html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      name: My Application Service
                      auto_resolve_timeout: 14400
                      acknowledgement_timeout: 600
                      created_at: '2015-11-06T11:12:51-05:00'
                      status: active
                      alert_creation: create_alerts_and_incidents
                      integrations:
                      - id: PQ12345
                        type: generic_email_inbound_integration_reference
                        summary: Email Integration
                        self: https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                        html_url: https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                      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
                      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'
                        days_of_week:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      scheduled_actions:
                      - type: urgency_change
                        at:
                          type: named_time
                          name: support_hours_start
                        to_urgency: high
                      auto_pause_notifications_parameters:
                        enabled: true
                        timeout: 300
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      x-pd-requires-scope: services.write
      tags:
      - Services
      operationId: deleteService
      description: 'Delete an existing service.


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


        A service may represent an application, component, or team you wish to open incidents against.


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Delete a service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: The service was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      x-pd-requires-scope: services.write
      tags:
      - Services
      description: 'Update an existing service.


        A service may represent an application, component, or team you wish to open incidents against.


        There is a limit of 100,000 open Incidents per Service. If the limit is reached and you disable `auto_resolve_timeout` (set to 0 or null), the API will respond with an error.


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Update a service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      operationId: updateService
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service:
                  $ref: '#/components/schemas/Service'
              required:
              - service
            examples:
              request:
                summary: Request Example
                value:
                  service:
                    type: service
                    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
                    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'
                      days_of_week:
                      - 1
                      - 2
                      - 3
                      - 4
                      - 5
                    scheduled_actions:
                    - type: urgency_change
                      at:
                        type: named_time
                        name: support_hours_start
                      to_urgency: high
                    alert_creation: create_alerts_and_incidents
                    alert_grouping_parameters:
                      type: time
                      config:
                        timeout: 2
                    auto_pause_notifications_parameters:
                      enabled: true
                      timeout: 300
        description: The service to be updated.
      responses:
        '200':
          description: The service that was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    $ref: '#/components/schemas/Service'
                required:
                - service
              examples:
                response:
                  summary: Response Example
                  value:
                    service:
                      id: PIJ90N7
                      type: service
                      summary: My Application Service
                      self: https://api.pagerduty.com/services/PIJ90N7
                      html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
                      name: My Application Service
                      auto_resolve_timeout: 14400
                      acknowledgement_timeout: 600
                      created_at: '2015-11-06T11:12:51-05:00'
                      status: active
                      alert_creation: create_alerts_and_incidents
                      alert_grouping_parameters:
                        type: time
                        config:
                          timeout: 2
                      integrations:
                      - id: PQ12345
                        type: generic_email_inbound_integration_reference
                        summary: Email Integration
                        self: https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                        html_url: https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345
                      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
                      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'
                        days_of_week:
                        - 1
                        - 2
                        - 3
                        - 4
                        - 5
                      scheduled_actions:
                      - type: urgency_change
                        at:
                          type: named_time
                          name: support_hours_start
                        to_urgency: high
                      auto_pause_notifications_parameters:
                        enabled: true
                        timeout: 300
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /services/{id}/audit/records:
    description: List audit records for a service.
    get:
      x-pd-requires-scope: audit_records.read
      tags:
      - Services
      operationId: listServiceAuditRecords
      summary: PagerDuty List audit records for a service
      description: 'The returned records are sorted by the `execution_time` from newest to oldest.


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


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


        Scoped OAuth requires: `audit_records.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/cursor_limit'
      - $ref: '#/components/parameters/cursor_cursor'
      - $ref: '#/components/parameters/audit_since'
      - $ref: '#/components/parameters/audit_until'
      responses:
        '200':
          description: Records matching the query criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditRecordResponseSchema'
              examples:
                response:
                  $ref: '#/components/examples/AuditRecordServiceResponse'
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /services/{id}/integrations:
    description: Create integrations belonging to a service.
    post:
      x-pd-requires-scope: services.write
      tags:
      - Services
      operationId: createServiceIntegration
      summary: PagerDuty Create a new integration
      description: 'Create a new integration belonging to a Service.


        A service may represent an application, component, or team you wish to open incidents against.


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


        Scoped OAuth requires: `services.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                integration:
                  $ref: '#/components/schemas/Integration'
              required:
              - integration
            examples:
              email_integration:
                summary: Request Example for Email Integration
                value:
                  integration:
                    type: generic_email_inbound_integration
                    name: Email
                    service:
                      id: PQL78HM
                      type: service_reference
                    integration_email: my-email-based-integration@subdomain.pagerduty.com
                    vendor:
                      type: vendor_reference
                      id: PZD94QK
              email_integration_with_filters:
                summary: Email Integration With Filters
                value:
                  integration:
                    type: generic_email_inbound_integration
                    name: Email with Filters
                    integration_email: your-service@subdomain.pd-staging.com
                    email_incident_creation: on_new_email_subject
                    email_filter_mode: or-rules-email
                    email_parsers:
                    - action: trigger
                      match_predicate:
                        type: any
                        matcher: this thing
                        part: body
                        children: []
                      value_extractors:
                      - type: entire
                        part: body
                        value_name: incident_key
                    email_parsing_fallback: discard
                    email_filters:
                    - subject_mode: match
                      subject_regex: alert
                      body_mode: match
                      body_regex: alert
                      from_email_mode: match
                      from_email_regex: alert
              events_v2_integration:
                summary: Request Example for Events v2 Integration
                value:
                  integration:
                    type: events_api_v2_inbound_integration
                    name: Events V2
                    service:
                      id: PQL78HM
                      type: service_reference
        description: The integration to be created
      responses:
        '201':
          description: The integration that was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  integration:
                    $ref: '#/components/schemas/Integration'
                required:
                - integration
              examples:
                response:
                  summary: Response Example
                  value:
                    integration:
                      id: PE1U9CH
                      type: generic_email_inbound_integration
                      summary: Email
                      self: https://api.pagerduty.com/services/PQL78HM/integrations/PE1U9CH
                      html_url: https://subdomain.pagerduty.com/services/PQL78HM/integrations/PE1U9CH
                      name: Email
                      service:
                        id: PQL78HM
                        type: service_reference
                        summary: My Email-Based Integration
                        self: https://api.pagerduty.com/services/PQL78HM
                        html_url: https://subdomain.pagerduty.com/service-directory/PQL78HM
                      created_at: '2015-10-14T13:33:02-07:00'
                      integration_email: my-email-based-integration@subdomain.pagerduty.com
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /services/{id}/integrations/{integration_id}:
    description: View or update integrations belonging to a service.
    put:
      x-pd-requires-scope: services.write
      tags:
      - Services
      operationId: updateServiceIntegration
      summary: PagerDuty Update an existing integration
      description: 'Update an integration belonging to a Service.


        A service may represent an application, component, or team you wish to open incidents against.


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


        Scoped OAuth requires: `services.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/integration_id'
      requestBody:
        content:
          application/json:
            sc

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