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=`