PagerDuty Notifications 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 Notifications API
  version: 2.0.0
servers:
- url: https://api.pagerduty.com
  description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Notifications
  description: 'A Notification is created when an Incident is triggered or escalated.

    '
paths:
  /notifications:
    description: List notifications that have been delivered to responders.
    get:
      x-pd-requires-scope: users:notifications.read
      tags:
      - Notifications
      operationId: listNotifications
      description: 'List notifications for a given time range, optionally filtered by type (sms_notification, email_notification, phone_notification, or push_notification).


        A Notification is created when an Incident is triggered or escalated.


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


        Scoped OAuth requires: `users:notifications.read`

        '
      summary: PagerDuty List notifications
      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'
      - $ref: '#/components/parameters/time_zone'
      - $ref: '#/components/parameters/since_notifications'
      - $ref: '#/components/parameters/until_notifications'
      - $ref: '#/components/parameters/filter_notifications'
      - $ref: '#/components/parameters/include_notifications'
      responses:
        '200':
          description: A paginated array of notifications.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Pagination'
                - type: object
                  properties:
                    notifications:
                      type: array
                      items:
                        $ref: '#/components/schemas/Notification'
                  required:
                  - notifications
              examples:
                response:
                  summary: Response Example
                  value:
                    notifications:
                    - id: PWL7QXS
                      type: phone_notification
                      started_at: '2013-03-06T15:28:51-05:00'
                      address: '+15555551234'
                      user:
                        id: PT23IWX
                        type: user_reference
                        summary: Tim Wright
                        self: https://api.pagerduty.com/users/PT23IWX
                        html_url: https://subdomain.pagerduty.com/users/PT23IWX
                    - id: PKN7NBH
                      type: push_notification
                      started_at: '2013-03-06T15:28:51-05:00'
                      user:
                        id: PT23IWX
                        type: user_reference
                        summary: Tim Wright
                        self: https://api.pagerduty.com/users/PT23IWX
                        html_url: https://subdomain.pagerduty.com/users/PT23IWX
                    limit: 100
                    offset: 0
                    more: false
                    total: null
        '400':
          $ref: '#/components/responses/ArgumentError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    since_notifications:
      name: since
      in: query
      description: The start of the date range over which you want to search. The time element is optional.
      required: true
      schema:
        type: string
        format: date-time
    include_notifications:
      name: include[]
      in: query
      description: Array of additional details to include.
      explode: true
      schema:
        type: string
        enum:
        - users
        uniqueItems: true
    offset_offset:
      name: offset
      in: query
      required: false
      description: Offset to start pagination search results.
      schema:
        type: integer
    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
    header_Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
        default: application/json
        enum:
        - application/json
    time_zone:
      name: time_zone
      in: query
      description: Time zone in which results will be rendered. This will default to the account time zone.
      schema:
        type: string
        format: tzinfo
    until_notifications:
      name: until
      in: query
      description: The end of the date range over which you want to search. This should be in the same format as since. The size of the date range must be less than 3 months.
      required: true
      schema:
        type: string
        format: date-time
    offset_total:
      name: total
      in: query
      required: false
      description: 'By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated.


        See our [Pagination Docs](https://developer.pagerduty.com/docs/rest-api-v2/pagination/) for more information.

        '
      schema:
        default: false
        type: boolean
    filter_notifications:
      name: filter
      in: query
      description: Return notification of this type only.
      schema:
        type: string
        enum:
        - sms_notification
        - email_notification
        - phone_notification
        - push_notification
    offset_limit:
      name: limit
      in: query
      required: false
      description: The number of results per page.
      schema:
        type: integer
  schemas:
    Notification:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        type:
          type: string
          description: The type of notification.
          enum:
          - sms_notification
          - email_notification
          - phone_notification
          - push_notification
          readOnly: true
        started_at:
          type: string
          format: date-time
          description: The time at which the notification was sent
          readOnly: true
        address:
          type: string
          description: The address where the notification was sent. This will be null for notification type `push_notification`.
          readOnly: true
        user:
          $ref: '#/components/schemas/UserReference'
        conferenceAddress:
          type: string
          description: The address of the conference bridge
        status:
          type: string
        ? ''
        : type: string
    UserReference:
      allOf:
      - $ref: '#/components/schemas/Reference'
      - type: object
        properties:
          type:
            type: string
            enum:
            - user_reference
    Reference:
      allOf:
      - $ref: '#/components/schemas/Tag/allOf/0'
      - type: object
        required:
        - type
        - id
    Pagination:
      type: object
      properties:
        offset:
          type: integer
          description: Echoes offset pagination property.
          readOnly: true
        limit:
          type: integer
          description: Echoes limit pagination property.
          readOnly: true
        more:
          type: boolean
          description: Indicates if there are additional records to return
          readOnly: true
        total:
          type: integer
          description: The total number of records matching the given query.
          nullable: true
          readOnly: true
    Tag:
      allOf:
      - type: object
        properties:
          id:
            type: string
            readOnly: true
          summary:
            type: string
            nullable: true
            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
            nullable: true
            readOnly: true
            format: url
            description: the API show URL at which the object is accessible
          html_url:
            type: string
            nullable: true
            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:
    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'
    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'
    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
    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'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header
      description: The API Key with format `Token token=<API_KEY>`