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 API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Abilities
  description: 'This describes your account''s abilities by feature name. For example `"teams"`.

    An ability may be available to your account based on things like your pricing plan or account state.

    '
paths:
  /abilities:
    description: List your account's abilities.
    get:
      x-pd-requires-scope: abilities.read
      tags:
      - Abilities
      operationId: listAbilities
      description: 'List all of your account''s abilities, by name.


        "Abilities" describes your account''s capabilities by feature name. For example `"teams"`.


        An ability may be available to your account based on things like your pricing plan or account state.


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


        Scoped OAuth requires: `abilities.read`

        '
      summary: PagerDuty List abilities
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      responses:
        '200':
          description: An array of ability names.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    abilities:
                      type: array
                      description: The set of abilities your account has.
                      items:
                        type: string
                        description: A single ability, as a name.
                        readOnly: true
                  required:
                  - abilities
              examples:
                response:
                  summary: Example Response
                  value:
                    abilities:
                    - teams
                    - read_only_users
                    - service_support_hours
                    - urgencies
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /abilities/{id}:
    description: Get an ability.
    get:
      x-pd-requires-scope: abilities.read
      tags:
      - Abilities
      operationId: getAbility
      description: 'Test whether your account has a given ability.


        "Abilities" describes your account''s capabilities by feature name. For example `"teams"`.


        An ability may be available to your account based on things like your pricing plan or account state.


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


        Scoped OAuth requires: `abilities.read`

        '
      summary: PagerDuty Test an ability
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: The account has the requested ability.
        '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'
components:
  responses:
    Conflict:
      description: The request conflicts with the current state of the server.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: integer
                    readOnly: true
                  message:
                    type: string
                    readOnly: true
                    description: Error message string
                  errors:
                    type: array
                    readOnly: true
                    items:
                      type: string
                      readOnly: true
                      description: Human-readable error details
                example:
                  message: Not Found
                  code: 2100
    PaymentRequired:
      description: 'Account does not have the abilities to perform the action. Please review the response for the required abilities.

        You can also use the [Abilities API](#resource_Abilities) to determine what features are available to your account.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    Unauthorized:
      description: 'Caller did not supply credentials or did not provide the correct credentials.

        If you are using an API key, it may be invalid or your Authorization header may be malformed.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    TooManyRequests:
      description: Too many requests have been made, the rate limit has been reached.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
    Forbidden:
      description: 'Caller is not authorized to view the requested resource.

        While your authentication is valid, the authenticated user or token does not have permission to perform this action.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
  parameters:
    header_Accept:
      name: Accept
      description: The `Accept` header is used as a versioning header.
      in: header
      required: true
      schema:
        type: string
        default: application/vnd.pagerduty+json;version=2
    id:
      name: id
      description: The ID of the resource.
      in: path
      required: true
      schema:
        type: string
    header_Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
        enum:
        - application/json
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: The API Key with format `Token token=<API_KEY>`