PagerDuty Business 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 Business Services API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Business Services
  description: 'Business services model capabilities that span multiple technical services and that may be owned by several different teams.

    '
paths:
  /business_services:
    description: List and create Business Services.
    get:
      x-pd-requires-scope: services.read
      tags:
      - Business Services
      operationId: listBusinessServices
      description: 'List existing Business Services.


        Business services model capabilities that span multiple technical services and that may be owned by several different teams.


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


        Scoped OAuth requires: `services.read`

        '
      summary: PagerDuty List Business Services
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/offset_limit'
      - $ref: '#/components/parameters/offset_offset'
      - $ref: '#/components/parameters/offset_total'
      responses:
        '200':
          description: A paginated array of services.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    business_services:
                      type: array
                      items:
                        $ref: '#/components/schemas/BusinessService'
                  required:
                  - business_services
              examples:
                response:
                  summary: Response Example
                  value:
                    business_services:
                    - type: business_service
                      self: https://api.pagerduty.com/business_services/P3U7V58
                      html_url: null
                      point_of_contact: PagerDuty Admin
                      name: stand-alone node
                      team: null
                      id: P3U7V58
                      description: Very important business function
                      summary: stand-alone node
                    - type: business_service
                      self: https://api.pagerduty.com/business_services/P1L1YEE
                      html_url: null
                      point_of_contact: PagerDuty Admin
                      name: Cross-tier business service
                      id: P1L1YEE
                      summary: Cross-tier business service
                      team:
                        id: PQ9K7I8
                        type: team_reference
                        self: https://api.pagerduty.com/teams/PQ9K7I8
                    limit: 100
                    offset: 0
                    total: null
                    more: false
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      x-pd-requires-scope: services.write
      tags:
      - Business Services
      operationId: createBusinessService
      description: 'Create a new Business Service.


        Business services model capabilities that span multiple technical services and that may be owned by several different teams.


        There is a limit of 5,000 business services per account. If the limit is reached, the API will respond with an error.


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Create a Business Service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_service:
                  type: object
                  description: The Business Service to be created
                  properties:
                    name:
                      type: string
                      description: The name of the Business Service.
                    description:
                      type: string
                      description: The description of the Business Service.
                    point_of_contact:
                      type: string
                      description: The owner of the Business Service.
                    team:
                      type: object
                      title: Team
                      description: Reference to the team that owns the Business Service.
                      properties:
                        id:
                          type: string
                          description: The Team ID
            examples:
              request:
                summary: Request Example
                value:
                  business_service:
                    name: Self-serve mobile checkout
                    description: Checkout service for our mobile clients
                    point_of_contact: PagerDuty Admin
                    team:
                      id: P3ZQXDF
      responses:
        '200':
          description: The Business Service that was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  business_service:
                    $ref: '#/components/schemas/BusinessService'
                required:
                - business_service
              examples:
                response:
                  summary: Response Example
                  value:
                    business_service:
                      id: P1L1YEE
                      type: business_service
                      self: https://api.pagerduty.com/business_services/P1L1YEE
                      html_url: null
                      point_of_contact: PagerDuty Admin
                      name: Self-serve mobile checkout
                      description: Checkout service for our mobile clients.
                      summary: Self-serve mobile checkout
                      team:
                        id: P3ZQXDF
                        type: team_reference
                        self: https://api.pagerduty.com/teams/P3ZQXDF
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /business_services/{id}:
    description: Manage a Business Service.
    get:
      x-pd-requires-scope: services.read
      tags:
      - Business Services
      operationId: getBusinessService
      description: 'Get details about an existing Business Service.


        Business services model capabilities that span multiple technical services and that may be owned by several different teams.


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


        Scoped OAuth requires: `services.read`

        '
      summary: PagerDuty Get a Business Service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The service business requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  business_service:
                    $ref: '#/components/schemas/BusinessService'
                required:
                - business_service
              examples:
                response:
                  summary: Response Example
                  value:
                    business_service:
                      id: P1L1YEE
                      type: business_service
                      self: https://api.pagerduty.com/business_services/P1L1YEE
                      html_url: null
                      name: Cross-tier business service
                      description: Business service affected by multiple teams
                      point_of_contact: PagerDuty Admin
                      summary: Cross-tier business services
                      team:
                        id: PQ9K7I8
                        type: team_reference
                        self: https://api.pagerduty.com/teams/PQ9K7I8
        '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:
      - Business Services
      operationId: deleteBusinessService
      description: 'Delete an existing Business 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.


        Business services model capabilities that span multiple technical services and that may be owned by several different teams.


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Delete a Business Service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: The Business Service was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      x-pd-requires-scope: services.write
      tags:
      - Business Services
      operationId: updateBusinessService
      description: 'Update an existing Business Service. NOTE that this endpoint also accepts the PATCH verb.


        Business services model capabilities that span multiple technical services and that may be owned by several different teams.


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


        Scoped OAuth requires: `services.write`

        '
      summary: PagerDuty Update a Business Service
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                business_service:
                  type: object
                  description: The Business Service to be created
                  properties:
                    name:
                      type: string
                      description: The name of the Business Service.
                    description:
                      type: string
                      description: The description of the Business Service.
                    point_of_contact:
                      type: string
                      description: The owner of the Business Service.
                    team:
                      type: object
                      title: Team
                      description: Reference to the team that owns the Business Service.
                      properties:
                        id:
                          type: string
                          description: The team ID
            examples:
              request:
                summary: Request Example
                value:
                  business_service:
                    name: Self-serve mobile checkout
                    description: Checkout service for our mobile clients
                    point_of_contact: PagerDuty Admin
                    team:
                      id: P3ZQXDF
      responses:
        '200':
          description: The Business Service that was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  business_service:
                    $ref: '#/components/schemas/BusinessService'
                required:
                - business_service
              examples:
                response:
                  summary: Response Example
                  value:
                    business_service:
                      id: P1L1YEE
                      type: business_service
                      self: https://api.pagerduty.com/business_services/P1L1YEE
                      html_url: null
                      point_of_contact: PagerDuty Admin
                      name: Self-serve mobile checkout
                      description: Checkout service for our mobile clients.
                      summary: Self-serve mobile checkout
                      team:
                        id: P3ZQXDF
                        type: team_reference
                        self: https://api.pagerduty.com/teams/P3ZQXDF
        '400':
          $ref: '#/components/responses/ArgumentError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /business_services/{id}/account_subscription:
    post:
      x-pd-requires-scope: subscribers.write
      summary: PagerDuty Create Business Service Account Subscription
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_is_subscribed:
                    type: boolean
                required:
                - account_is_subscribed
              examples:
                response:
                  summary: Response Example
                  value:
                    account_is_subscribed: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      operationId: createBusinessServiceAccountSubscription
      description: 'Subscribe your Account to a Business Service.


        Scoped OAuth requires: `subscribers.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
    delete:
      x-pd-requires-scope: subscribers.write
      summary: PagerDuty Delete Business Service Account Subscription
      tags:
      - Business Services
      operationId: removeBusinessServiceAccountSubscription
      responses:
        '204':
          description: The account was unsubscribed successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      description: 'Unsubscribe your Account from a Business Service.


        Scoped OAuth requires: `subscribers.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
  /business_services/{id}/subscribers:
    get:
      x-pd-requires-scope: subscribers.read
      summary: PagerDuty List Business Service Subscribers
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    subscribers:
                      type: array
                      items:
                        $ref: '#/components/schemas/NotificationSubscriber'
                - type: object
                  properties:
                    account_id:
                      type: string
                      description: The ID of the account belonging to the subscriber entity
              examples:
                response:
                  summary: Response Example
                  value:
                    limit: 100
                    more: false
                    offset: 0
                    subscribers:
                    - subscriber_id: PD1234
                      subscriber_type: user
                    - subscriber_id: PD1234
                      subscriber_type: team
                    account_id: PD1234
                    total: 2
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getBusinessServiceSubscribers
      description: 'Retrieve a list of Notification Subscribers on the Business Service.


        <!-- theme: warning -->

        > Users must be added through `POST /business_services/{id}/subscribers` to be returned from this endpoint.

        Scoped OAuth requires: `subscribers.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
    post:
      x-pd-requires-scope: subscribers.write
      summary: PagerDuty Create Business Service Subscribers
      tags:
      - Business Services
      operationId: createBusinessServiceNotificationSubscribers
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationSubscriptionWithContext'
              examples:
                response:
                  summary: Response Example
                  value:
                    subscriptions:
                    - account_id: PD1234
                      subscribable_id: PD1234
                      subscribable_type: business_service
                      subscriber_id: PD1234
                      subscriber_type: user
                      result: success
                    - account_id: PD1234
                      subscribable_id: PD1234
                      subscribable_type: business_service
                      subscriber_id: PD1234
                      subscriber_type: team
                      result: duplicate
                    - account_id: PD1234
                      subscribable_id: PD1235
                      subscribable_type: business_service
                      subscriber_id: PD1234
                      subscriber_type: team
                      result: unauthorized
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      description: 'Subscribe the given entities to the given Business Service.


        Scoped OAuth requires: `subscribers.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscribers:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/NotificationSubscriber'
              required:
              - subscribers
            examples:
              request:
                summary: Request Example
                value:
                  subscribers:
                  - subscriber_id: PD1234
                    subscriber_type: team
                  - subscriber_id: PD1235
                    subscriber_type: team
                  - subscriber_id: PD1234
                    subscriber_type: user
        description: The entities to subscribe.
  /business_services/{id}/supporting_services/impacts:
    get:
      x-pd-requires-scope: services.read
      summary: PagerDuty List the supporting Business Services for the given Business Service Id, sorted by impacted status.
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LiveListResponse'
                - type: object
                  properties:
                    services:
                      type: array
                      items:
                        $ref: '#/components/schemas/Impact'
                - type: object
                  properties:
                    additional_fields:
                      type: object
                      properties:
                        total_impacted_count:
                          type: integer
              examples:
                response:
                  summary: Response Example
                  value:
                    limit: 100
                    more: false
                    services:
                    - id: PD1234
                      name: Web API
                      type: business_service
                      status: impacted
                      additional_fields:
                        highest_impacting_priority:
                          id: PQOMK4S
                          order: 128
                    - id: PF9KMXH
                      name: Analytics Backend
                      type: business_service
                      status: not_impacted
                      additional_fields:
                        highest_impacting_priority: null
                    additional_fields:
                      total_impacted_count: 1
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getBusinessServiceSupportingServiceImpacts
      description: 'Retrieve of Business Services that support the given Business Service sorted by highest Impact with `status` included.

        This endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted up to the limit of 200.


        The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name.


        To get impact information about a specific set of Business Services, use the `ids[]` parameter on the `/business_services/impacts` endpoint.

        Scoped OAuth requires: `services.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/impacts_additional_fields'
      - $ref: '#/components/parameters/ids'
  /business_services/{id}/unsubscribe:
    post:
      x-pd-requires-scope: subscribers.write
      summary: PagerDuty Remove Business Service Subscribers
      tags:
      - Business Services
      operationId: removeBusinessServiceNotificationSubscriber
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: number
                  unauthorized_count:
                    type: number
                  non_existent_count:
                    type: number
                required:
                - deleted_count
                - unauthorized_count
                - non_existent_count
              examples:
                response:
                  summary: Response Example
                  value:
                    deleted_count: 1
                    unauthorized_count: 1
                    non_existent_count: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      description: 'Unsubscribes the matching Subscribers from a Business Service.


        Scoped OAuth requires: `subscribers.write`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscribers:
                  type: array
                  uniqueItems: true
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/NotificationSubscriber'
              required:
              - subscribers
            examples:
              request:
                summary: Request Example
                value:
                  subscribers:
                  - subscriber_id: PD1234
                    subscriber_type: team
                  - subscriber_id: PD1234
                    subscriber_type: user
        description: The entities to unsubscribe.
  /business_services/impactors:
    get:
      x-pd-requires-scope: services.read
      summary: PagerDuty List Impactors affecting Business Services
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LiveListResponse'
                - type: object
                  properties:
                    impactors:
                      type: array
                      items:
                        $ref: '#/components/schemas/Impactor'
              examples:
                response:
                  summary: Response Example
                  value:
                    limit: 100
                    more: false
                    impactors:
                    - id: PD1234
                      type: incident
                    - id: PF9KMXH
                      type: incident
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getBusinessServiceTopLevelImpactors
      description: 'Retrieve a list of Impactors for the top-level Business Services on the account. Impactors are currently limited to Incidents.


        This endpoint does not return an exhaustive list of Impactors but rather provides access to the highest priority Impactors for the Business Services in question up to the limit of 200.


        To get Impactors for a specific set of Business Services, use the `ids[]` parameter.


        The returned Impactors are sorted first by priority and secondarily by their creation date.

        Scoped OAuth requires: `services.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/ids'
  /business_services/impacts:
    get:
      x-pd-requires-scope: services.read
      summary: PagerDuty List Business Services sorted by impacted status
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/LiveListResponse'
                - type: object
                  properties:
                    services:
                      type: array
                      items:
                        $ref: '#/components/schemas/Impact'
                - type: object
                  properties:
                    additional_fields:
                      type: object
                      properties:
                        total_impacted_count:
                          type: integer
              examples:
                response:
                  summary: Response Example
                  value:
                    limit: 100
                    more: false
                    services:
                    - id: PD1234
                      name: Web API
                      type: business_service
                      status: impacted
                      additional_fields:
                        highest_impacting_priority:
                          id: PQOMK4S
                          order: 128
                    - id: PF9KMXH
                      name: Analytics Backend
                      type: business_service
                      status: not_impacted
                      additional_fields:
                        highest_impacting_priority: null
                    additional_fields:
                      total_impacted_count: 1
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      operationId: getBusinessServiceImpacts
      description: 'Retrieve a list top-level Business Services sorted by highest Impact with `status` included.

        When called without the `ids[]` parameter, this endpoint does not return an exhaustive list of Business Services but rather provides access to the most impacted up to the limit of 200.


        The returned Business Services are sorted first by Impact, secondarily by most recently impacted, and finally by name.


        To get impact information about a specific set of Business Services, use the `ids[]` parameter.

        Scoped OAuth requires: `services.read`

        '
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/impacts_additional_fields'
      - $ref: '#/components/parameters/ids'
  /business_services/priority_thresholds:
    get:
      x-pd-requires-scope: services.read
      summary: PagerDuty Get the global priority threshold for a Business Service to be considered impacted by an Incident
      tags:
      - Business Services
      responses:
        '200':
          description: OK
          content:
      

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