PagerDuty Maintenance Windows API
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/pagerduty-maintenance-windows-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
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 Maintenance Windows API
version: 2.0.0
servers:
- url: https://api.pagerduty.com
description: PagerDuty V2 API.
security:
- api_key: []
tags:
- name: Maintenance Windows
description: A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
paths:
/maintenance_windows:
description: List and create maintenance windows.
get:
x-pd-requires-scope: services.read
tags:
- Maintenance Windows
operationId: listMaintenanceWindows
description: 'List existing maintenance windows, optionally filtered by service and/or team, or whether they are from the past, present or future.
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
For more information see the API Concepts Document
Scoped OAuth requires: `services.read`'
summary: PagerDuty List maintenance windows
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/offset_limit'
- $ref: '#/components/parameters/offset_offset'
- $ref: '#/components/parameters/offset_total'
- $ref: '#/components/parameters/team_ids'
- $ref: '#/components/parameters/services'
- $ref: '#/components/parameters/include_maintenance_window'
- $ref: '#/components/parameters/filter_maintenance_windows'
responses:
'200':
description: A paginated array of maintenance windows.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Pagination'
- type: object
properties:
maintenance_windows:
type: array
items:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_windows
examples:
response:
summary: Response Example
value:
maintenance_windows:
- id: PW98YIO
type: maintenance_window
summary: Immanentizing the eschaton
self: https://api.pagerduty.com/maintenance_windows/PW98YIO
html_url: https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO
sequence_number: 1
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
summary: My Mail Service
self: https://api.pagerduty.com/services/PIJ90N7
html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
teams:
- id: PQ9K7I8
type: team_reference
summary: Engineering
self: https://api.pagerduty.com/teams/PQ9K7I8
html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
created_by:
id: PXPGF42
type: user_reference
summary: Earline Greenholt
self: https://api.pagerduty.com/users/PXPGF42
html_url: https://subdomain.pagerduty.com/users/PXPGF42
limit: 25
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'
post:
x-pd-requires-scope: services.write
tags:
- Maintenance Windows
operationId: createMaintenanceWindow
description: 'Create a new maintenance window for the specified services. No new incidents will be created for a service that is in maintenance.
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
For more information see the API Concepts Document
Scoped OAuth requires: `services.write`'
summary: PagerDuty Create a maintenance window
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:
maintenance_window:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_window
examples:
request:
summary: Request Example
value:
maintenance_window:
type: maintenance_window
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
description: The maintenance window object.
responses:
'201':
description: The maintenance window that was created.
content:
application/json:
schema:
type: object
properties:
maintenance_window:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_window
examples:
response:
summary: Response Example
value:
maintenance_window:
id: PW98YIO
type: maintenance_window
summary: Immanentizing the eschaton
self: https://api.pagerduty.com/maintenance_windows/PW98YIO
html_url: https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO
sequence_number: 1
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
summary: My Mail Service
self: https://api.pagerduty.com/services/PIJ90N7
html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
teams:
- id: PQ9K7I8
type: team_reference
summary: Engineering
self: https://api.pagerduty.com/teams/PQ9K7I8
html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
created_by:
id: PXPGF42
type: user_reference
summary: Earline Greenholt
self: https://api.pagerduty.com/users/PXPGF42
html_url: https://subdomain.pagerduty.com/users/PXPGF42
'400':
$ref: '#/components/responses/ArgumentError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
/maintenance_windows/{id}:
description: Manage a maintenance window.
get:
x-pd-requires-scope: services.read
tags:
- Maintenance Windows
operationId: getMaintenanceWindow
description: 'Get an existing maintenance window.
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
For more information see the API Concepts Document
Scoped OAuth requires: `services.read`'
summary: PagerDuty Get a maintenance window
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/include_maintenance_window'
responses:
'200':
description: The maintenance window that was updated.
content:
application/json:
schema:
type: object
properties:
maintenance_window:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_window
examples:
response:
summary: Response Example
value:
maintenance_window:
id: PW98YIO
type: maintenance_window
summary: Immanentizing the eschaton
self: https://api.pagerduty.com/maintenance_windows/PW98YIO
html_url: https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO
sequence_number: 1
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
summary: My Mail Service
self: https://api.pagerduty.com/services/PIJ90N7
html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
teams:
- id: PQ9K7I8
type: team_reference
summary: Engineering
self: https://api.pagerduty.com/teams/PQ9K7I8
html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
created_by:
id: PXPGF42
type: user_reference
summary: Earline Greenholt
self: https://api.pagerduty.com/users/PXPGF42
html_url: https://subdomain.pagerduty.com/users/PXPGF42
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
x-pd-requires-scope: services.write
tags:
- Maintenance Windows
operationId: deleteMaintenanceWindow
description: 'Delete an existing maintenance window if it''s in the future, or end it if it''s currently on-going. If the maintenance window has already ended it cannot be deleted.
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
For more information see the API Concepts Document
Scoped OAuth requires: `services.write`'
summary: PagerDuty Delete or end a maintenance window
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
responses:
'204':
description: The maintenance window was deleted successfully.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'405':
description: The maintenance window can't be deleted because it has already ended.
'429':
$ref: '#/components/responses/TooManyRequests'
put:
x-pd-requires-scope: services.write
tags:
- Maintenance Windows
operationId: updateMaintenanceWindow
description: 'Update an existing maintenance window.
A Maintenance Window is used to temporarily disable one or more Services for a set period of time.
For more information see the API Concepts Document
Scoped OAuth requires: `services.write`'
summary: PagerDuty Update a maintenance window
parameters:
- $ref: '#/components/parameters/header_Accept'
- $ref: '#/components/parameters/header_Content-Type'
- $ref: '#/components/parameters/id'
requestBody:
content:
application/json:
schema:
type: object
properties:
maintenance_window:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_window
examples:
request:
summary: Request Example
value:
maintenance_window:
type: maintenance_window
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
description: The maintenance window to be updated.
responses:
'200':
description: The maintenance window that was updated.
content:
application/json:
schema:
type: object
properties:
maintenance_window:
$ref: '#/components/schemas/MaintenanceWindow'
required:
- maintenance_window
examples:
response:
summary: Response Example
value:
maintenance_window:
id: PW98YIO
type: maintenance_window
summary: Immanentizing the eschaton
self: https://api.pagerduty.com/maintenance_windows/PW98YIO
html_url: https://subdomain.pagerduty.com/service-directory/maintenance-windows/PW98YIO
sequence_number: 1
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
summary: My Mail Service
self: https://api.pagerduty.com/services/PIJ90N7
html_url: https://subdomain.pagerduty.com/service-directory/PIJ90N7
teams:
- id: PQ9K7I8
type: team_reference
summary: Engineering
self: https://api.pagerduty.com/teams/PQ9K7I8
html_url: https://subdomain.pagerduty.com/teams/PQ9K7I8
created_by:
id: PXPGF42
type: user_reference
summary: Earline Greenholt
self: https://api.pagerduty.com/users/PXPGF42
html_url: https://subdomain.pagerduty.com/users/PXPGF42
'400':
$ref: '#/components/responses/ArgumentError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
ServiceReference:
allOf:
- $ref: '#/components/schemas/Reference'
- type: object
properties:
type:
type: string
enum:
- service_reference
UserReference:
allOf:
- $ref: '#/components/schemas/Reference'
- type: object
properties:
type:
type: string
enum:
- user_reference
MaintenanceWindow:
allOf:
- $ref: '#/components/schemas/Tag/allOf/0'
- type: object
properties:
type:
type: string
description: The type of object being created.
default: maintenance_window
enum:
- maintenance_window
sequence_number:
type: integer
readOnly: true
description: The order in which the maintenance window was created.
start_time:
type: string
format: date-time
description: This maintenance window's start time. This is when the services will stop creating incidents. If this date is in the past, it will be updated to be the current time.
end_time:
type: string
format: date-time
description: This maintenance window's end time. This is when the services will start creating incidents again. This date must be in the future and after the `start_time`.
description:
type: string
description: A description for this maintenance window.
created_by:
$ref: '#/components/schemas/UserReference'
services:
type: array
items:
$ref: '#/components/schemas/ServiceReference'
teams:
type: array
items:
$ref: '#/components/schemas/TeamReference'
readOnly: true
required:
- start_time
- end_time
- services
- type
example:
id: PIJ89JD
type: maintenance_window
start_time: '2015-11-09T20:00:00-05:00'
end_time: '2015-11-09T22:00:00-05:00'
description: Immanentizing the eschaton
services:
- id: PIJ90N7
type: service_reference
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
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
- 'null'
description: The total number of records matching the given query.
readOnly: true
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
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'
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'
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'
NotFound:
description: The requested resource was not found.
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'
parameters:
include_maintenance_window:
name: include[]
in: query
description: Array of additional Models to include in response.
explode: true
schema:
type: string
enum:
- teams
- services
- users
uniqueItems: true
query:
name: query
in: query
description: Filters the result, showing only the records whose name matches the query.
required: false
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_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
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
header_Content-Type:
name: Content-Type
in: header
required: true
schema:
type: string
default: application/json
enum:
- application/json
offset_offset:
name: offset
in: query
required: false
description: Offset to start pagination search results.
schema:
type: integer
filter_maintenance_windows:
name: filter
in: query
description: Only return maintenance windows in a given state.
schema:
type: string
enum:
- past
- future
- ongoing
- open
- all
services:
name: service_ids[]
in: query
description: An array of service IDs. Only results related to these services will be returned.
explode: true
schema:
type: array
items:
type: string
team_ids:
name: team_ids[]
in: query
description: An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.
explode: true
schema:
type: array
items:
type: string
uniqueItems: true
offset_limit:
name: limit
in: query
required: false
description: The number of results per page.
schema:
type: integer
securitySchemes:
api_key:
type: apiKey
name: Authorization
in: header
description: The API Key with format `Token token=<API_KEY>`