PagerDuty Response Plays API

openapi: 3.2.0
info:
  description: 'This document describes the PagerDuty REST APIs.


    For guides and examples please visit our Documentation.


    Our REST APIs are defined in OpenAPI v3.x. You can view the schema at 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 Response Plays API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Response Plays
  description: Response Plays are a package of Incident Actions that can be applied during an Incident's life cycle.
paths:
  /response_plays:
    description: List and create response plays.
    get:
      x-pd-requires-scope: response_plays.read
      deprecated: true
      tags:
      - Response Plays
      operationId: listResponsePlays
      description: 'List all of the existing Response Plays.


        Response Plays allow you to create packages of Incident Actions that can be applied during an Incident''s life cycle.


        For more information see the API Concepts Document


        When using a Global API token, the `From` header is required.


        Scoped OAuth requires: `response_plays.read`'
      summary: PagerDuty List Response Plays
      parameters:
      - $ref: '#/components/parameters/query'
      - $ref: '#/components/parameters/filter_for_manual_run'
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/optional_from_header'
      responses:
        '200':
          description: The array of Response Plays returned by the query.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_plays:
                    type: array
                    items:
                      $ref: '#/components/schemas/ResponsePlay'
              examples:
                response:
                  summary: Response Example
                  value:
                    response_plays:
                    - type: response_play
                      team: null
                      summary: An Existing Response Play For Responders
                      self: https://api.pagerduty.com/response_plays/15b4b27e-2448-adf9-c5a5-85382304ff37
                      name: An Existing Response Play For Responders
                      id: 15b4b27e-2448-adf9-c5a5-85382304ff37
                      html_url: null
                      description: A Response Play that adds responders.
                    - type: response_play
                      team: null
                      summary: An Existing Response Play For Subscribers
                      self: https://api.pagerduty.com/response_plays/15b4b27e-2771-abe5-t6m9-81234304ff37
                      name: An Existing Response Play For Subscribers
                      id: 15b4b27e-2771-abe5-t6m9-81234304ff37
                      html_url: null
                      description: A Response Play that adds subscribers.
                    limit: null
                    offset: null
                    total: 2
                    more: false
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      deprecated: true
      x-pd-requires-scope: response_plays.write
      tags:
      - Response Plays
      operationId: createResponsePlay
      description: 'Creates a new Response Plays.


        Response Plays allow you to create packages of Incident Actions that can be applied during an Incident''s life cycle.


        For more information see the API Concepts Document


        Scoped OAuth requires: `response_plays.write`'
      summary: PagerDuty Create a Response Play
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                response_play:
                  $ref: '#/components/schemas/ResponsePlay'
              required:
              - response_play
            examples:
              Example1:
                summary: Create a Response Play which adds a Escalation Policy and User to an incident when the response play is run
                value:
                  response_play:
                    type: response_play
                    team: null
                    name: Standard NOC-EP
                    description: A Response Play to add NOC EP on Run
                    subscribers: []
                    subscribers_message: null
                    responders:
                    - type: user_reference
                      id: PROW72A
                      summary: our team stakeholder
                    - type: escalation_policy_reference
                      id: P12TU3X
                      summary: Network Center Escalation Policy
                    responders_message: NOC-EP
                    runnability: services
              Example2:
                summary: Add a static conference url to an incident when the response play is run
                value:
                  response_play:
                    type: response_play
                    name: Basic Fixed URL
                    description: preset conference url
                    runnability: services
                    conference_url: https://my.conference.com/our_team/123
        description: The Response Play to be created.
      responses:
        '201':
          description: The Response Play that was created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_play:
                    $ref: '#/components/schemas/ResponsePlay'
              examples:
                response:
                  summary: Response Example
                  value:
                    response_play:
                      type: response_play
                      team: null
                      summary: A New Response Play
                      subscribers_message: Please view the attached incident.
                      subscribers:
                      - type: user_reference
                        summary: null
                        self: https://api.pagerduty.com/users/PSEJLIN
                        id: PSEJLIN
                        html_url: null
                      - type: team_reference
                        summary: null
                        self: https://api.pagerduty.com/teams/P12TU3X
                        id: P12TU3X
                        html_url: null
                      self: https://api.pagerduty.com/response_plays/15b4b27e-2448-adf9-c5a5-85382304ff37
                      runnability: services
                      responders_message: We need executive attention on this incident.
                      responders:
                      - type: user_reference
                        summary: null
                        self: https://api.pagerduty.com/users/PZOW51A
                        id: PZOW51A
                        html_url: null
                      name: A New Response Play
                      id: 15b4b27e-2448-adf9-c5a5-85382304ff37
                      html_url: null
                      description: A Response Play that adds subscribers and responders
                      conference_url: null
                      conference_number: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /response_plays/{id}:
    description: Manage a Response Play.
    get:
      deprecated: true
      x-pd-requires-scope: response_plays.read
      tags:
      - Response Plays
      operationId: getResponsePlay
      description: 'Get details about an existing Response Play.


        Response Plays allow you to create packages of Incident Actions that can be applied during an Incident''s life cycle.


        For more information see the API Concepts Document


        When using a Global API token, the `From` header is required.

        Scoped OAuth requires: `response_plays.read`'
      summary: PagerDuty Get a Response Play
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/optional_from_header'
      responses:
        '200':
          description: The Response Play requested.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_play:
                    $ref: '#/components/schemas/ResponsePlay'
              examples:
                response:
                  summary: Response Example
                  value:
                    response_play:
                      type: response_play
                      team: null
                      summary: Email Service Response Play
                      subscribers_message: null
                      subscribers: null
                      self: https://api.pagerduty.com/response_plays/15b4b27e-2448-adf9-c5a5-85382304ff37
                      runnability: services
                      responders_message: null
                      responders:
                      - type: escalation_policy_reference
                        summary: null
                        self: https://api.pagerduty.com/escalation_policies/PZOW51A
                        id: PZOW51A
                        html_url: null
                      name: Email Service Response Play
                      id: 15b4b27e-2448-adf9-c5a5-85382304ff37
                      html_url: null
                      description: null
                      conference_url: null
                      conference_number: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      deprecated: true
      x-pd-requires-scope: response_plays.write
      tags:
      - Response Plays
      operationId: updateResponsePlay
      description: 'Updates an existing Response Play.


        Response Plays allow you to create packages of Incident Actions that can be applied during an Incident''s life cycle.


        For more information see the API Concepts Document


        Scoped OAuth requires: `response_plays.write`'
      summary: PagerDuty Update a Response Play
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                response_play:
                  $ref: '#/components/schemas/ResponsePlay'
              required:
              - response_play
            examples:
              request:
                summary: Request Example
                value:
                  response_play:
                    type: response_play
                    team: null
                    summary: Test Response Play
                    subscribers_message: Please view the attached incident.
                    subscribers:
                    - type: user_reference
                      id: PFS9QZZ
                    self: https://api.pagerduty.com/response_plays/153d9e1f-9008-ee4e-fa70-0d70cdf92f27
                    runnability: responders
                    responders_message: null
                    responders: []
                    name: Test Response Play
                    id: 153d9e1f-9008-ee4e-fa70-0d70cdf92f27
                    html_url: null
                    description: An updated description of this Response Play.
                    conference_url: null
                    conference_number: null
        description: The Response Play to be updated.
      responses:
        '200':
          description: The Response Play that was updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response_play:
                    $ref: '#/components/schemas/ResponsePlay'
              examples:
                response:
                  summary: Response Example
                  value:
                    response_play:
                      type: response_play
                      team: null
                      summary: Test Response Play
                      subscribers_message: Please view the attached incident.
                      subscribers:
                      - type: user_reference
                        summary: null
                        self: https://api.pagerduty.com/users/PFS9QZZ
                        id: PFS9QZZ
                        html_url: null
                      self: https://api.pagerduty.com/response_plays/153d9e1f-9008-ee4e-fa70-0d70cdf92f27
                      runnability: services
                      responders_message: null
                      responders: []
                      name: Test Response Play
                      id: 153d9e1f-9008-ee4e-fa70-0d70cdf92f27
                      html_url: null
                      description: null
                      conference_url: null
                      conference_number: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      deprecated: true
      x-pd-requires-scope: response_plays.write
      tags:
      - Response Plays
      operationId: deleteResponsePlay
      description: 'Delete an existing Response Play. Once the Response Play is deleted, the action cannot be undone.


        WARNING: When the Response Play is deleted, it is also removed from any Services that were using it.


        Response Plays allow you to create packages of Incident Actions that can be applied to an Incident.


        For more information see the API Concepts Document


        Scoped OAuth requires: `response_plays.write`'
      summary: PagerDuty Delete a Response Play
      parameters:
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/from_header'
      responses:
        '204':
          description: The Response Play was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /response_plays/{response_play_id}/run:
    description: Run response plays.
    post:
      x-pd-requires-scope: response_plays.write
      deprecated: true
      tags:
      - Response Plays
      operationId: runResponsePlay
      description: 'Run a specified response play on a given incident.


        Response Plays are a package of Incident Actions that can be applied during an Incident''s life cycle.


        For more information see the API Concepts Document


        Scoped OAuth requires: `response_plays.write`'
      summary: PagerDuty Run a response play
      parameters:
      - $ref: '#/components/parameters/header_Accept'
      - $ref: '#/components/parameters/header_Content-Type'
      - $ref: '#/components/parameters/response_play_id'
      - $ref: '#/components/parameters/from_header'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                incident:
                  $ref: '#/components/schemas/IncidentReference'
              required:
              - incident
            examples:
              request:
                summary: Request Example
                value:
                  incident:
                    id: PWL7QXS
                    type: incident_reference
      responses:
        '200':
          description: Informs the user if the response play has been run successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                required:
                - status
              examples:
                response:
                  summary: Response Example
                  value:
                    status: ok
        '400':
          $ref: '#/components/responses/ArgumentError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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
    response_play_id:
      name: response_play_id
      in: path
      description: The response play ID of the response play associated with the request.
      required: true
      schema:
        type: string
    from_header:
      name: From
      in: header
      description: The email address of a valid user associated with the account making the request.
      required: true
      schema:
        type: string
        format: email
    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
    filter_for_manual_run:
      name: filter_for_manual_run
      in: query
      description: When this parameter is present, only those Response Plays that can be run manually will be returned.
      schema:
        type: boolean
    optional_from_header:
      name: From
      in: header
      description: The email address of a valid user associated with the account making the request. This is optional, and is only used for change tracking.
      required: false
      schema:
        type: string
        format: email
    query:
      name: query
      in: query
      description: Filters the result, showing only the records whose name matches the query.
      required: false
      schema:
        type: string
  schemas:
    EscalationPolicyReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - escalation_policy_reference
    UserReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - user_reference
    IncidentReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - incident_reference
    TeamReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - team_reference
    Reference:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        required:
        - type
        - id
    ResponsePlay:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        properties:
          type:
            type: string
            description: The type of object being created.
            default: response_play
            enum:
            - response_play
          name:
            type: string
            description: The name of the response play.
          description:
            type:
            - string
            - 'null'
            description: The description of the response play.
            maxLength: 349
          team:
            oneOf:
            - $ref: '#/components/schemas/TeamReference'
            - type:
              - object
              - 'null'
          subscribers:
            type:
            - array
            - 'null'
            description: An array containing the users and/or teams to be added as subscribers to any incident on which this response play is run.
            items:
              anyOf:
              - $ref: '#/components/schemas/UserReference'
              - $ref: '#/components/schemas/TeamReference'
              discriminator:
                propertyName: type
          subscribers_message:
            type:
            - string
            - 'null'
            description: The content of the notification that will be sent to all incident subscribers upon the running of this response play. Note that this includes any users who may have already been subscribed to the incident prior to the running of this response play. If empty, no notifications will be sent.
          responders:
            type: array
            description: An array containing the users and/or escalation policies to be requested as responders to any incident on which this response play is run.
            items:
              anyOf:
              - $ref: '#/components/schemas/UserReference'
              - $ref: '#/components/schemas/EscalationPolicyReference'
              discriminator:
                propertyName: type
          responders_message:
            type:
            - string
            - 'null'
            description: The message body of the notification that will be sent to this response play's set of responders. If empty, a default response request notification will be sent.
          runnability:
            type: string
            description: "String representing how this response play is allowed to be run. Valid options are:\n  - `services`: This response play cannot be manually run by any users. It will run automatically for new incidents triggered on any services that are configured with this response play.\n  - `teams`: This response play can be run manually on an incident only by members of its configured team. This option can only be selected when the `team` property for this response play is not empty.\n  - `responders`: This response play can be run manually on an incident by any responders in this account."
            enum:
            - services
            - teams
            - responders
            default: services
          conference_number:
            type:
            - string
            - 'null'
            description: The telephone number that will be set as the conference number for any incident on which this response play is run.
          conference_url:
            type:
            - string
            - 'null'
            description: The URL that will be set as the conference URL for any incident on which this response play is run.
          conference_type:
            type: string
            description: "This field has three possible values and indicates how the response play was created.\n  - `none` : The response play had no conference_number or conference_url set at time of creation.\n  - `manual` : The response play had one or both of conference_number and conference_url set at time of creation.\n  - `zoom` : Customers with the Zoom-Integration Entitelment can use this value to dynamicly configure conference number and url for zoom"
            enum:
            - none
            - manual
            - zoom
            default: none
    Tag:
      allOf:
      - type: object
        properties:
          id:
            type: string
            readOnly: true
          summary:
            type:
            - string
            - 'null'
            readOnly: true
            description: A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier.
          type:
            type: string
            readOnly: true
            description: A string that determines the schema of the object. This must be the standard name for the entity, suffixed by `_reference` if the object is a reference.
          self:
            type:
            - string
            - 'null'
            readOnly: true
            format: url
            description: the API show URL at which the object is accessible
          html_url:
            type:
            - string
            - 'null'
            readOnly: true
            format: url
            description: a URL at which the entity is uniquely displayed in the Web app
      - type: object
        properties:
          type:
            type: string
            description: The type of object being created.
            default: tag
            enum:
            - tag
          label:
            type: string
            description: The label of the tag.
            maxLength: 191
        required:
        - label
        - type
        example:
          type: tag
          label: Batman
  responses:
    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'
    NotFound:
      description: The requested resource was not found.
      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'
    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'
    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
    ArgumentError:
      description: Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.
      content:
        application/json:
          schema:
            $ref: '#/components/responses/Conflict/content/application~1json/schema'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: The API Key with format `Token token=<API_KEY>`