API & Developers

Manage project maintenance with the API

Use the maintenance API to coordinate a project's alert-suppression window from deployment or operations automation.

Authorization

Send a project-scoped Bearer token with every request:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Read endpoints require project_maintenances:read. Write endpoints require project_maintenances:write, and the token owner must currently have a Developer or Admin role on the project. The numeric {project} must match the project assigned to the token.

Tokens created from Settings > API Tokens receive both maintenance abilities. See Create and use API tokens for storage and revocation guidance.

Endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/projects/{project}/maintenance`	Retrieve the scheduled or active window, or `data: null` when none exists.
`GET`	`/api/v1/projects/{project}/maintenances`	List maintenance history, newest start time first.
`POST`	`/api/v1/projects/{project}/maintenances`	Create scheduled or active maintenance.
`GET`	`/api/v1/projects/{project}/maintenances/{maintenance}`	Retrieve one maintenance record.
`PATCH`	`/api/v1/projects/{project}/maintenances/{maintenance}`	Update a scheduled or active record.
`POST`	`/api/v1/projects/{project}/maintenances/{maintenance}/end`	End active maintenance now.
`POST`	`/api/v1/projects/{project}/maintenances/{maintenance}/cancel`	Cancel scheduled maintenance.

The history endpoint accepts source=manual, source=api, or source=system. It also accepts per_page from 1 to 100 and defaults to 15.

Create maintenance

Send any of these JSON fields:

starts_at: optional date/time; defaults to the request time when omitted.
ends_at: optional future date/time; when present, it must be after starts_at.
details: optional string up to 5,000 characters.

Do not send source. DeployMonitor assigns api to records created by this endpoint.

curl --fail-with-body \
  --request POST \
  "https://deploymonitor.com/api/v1/projects/${DEPLOYMONITOR_PROJECT_ID}/maintenances" \
  --header "Authorization: Bearer ${DEPLOYMONITOR_TOKEN}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "starts_at": "2026-08-26T06:00:00Z",
    "ends_at": "2026-08-26T06:30:00Z",
    "details": "Deploying the production release."
  }'

A successful create request returns 201 Created.

Update, end, or cancel maintenance

A PATCH request accepts starts_at, ends_at, and details. Omit fields that should remain unchanged. Send ends_at: null to remove a planned end time.

Lifecycle rules apply:

Only one scheduled or active window can exist for a project.
Completed or cancelled records cannot be updated.
The start time cannot be changed after maintenance becomes active.
Only active maintenance can be ended.
Only scheduled maintenance can be cancelled.

Violating a lifecycle rule returns 409 Conflict. Invalid fields return 422 Unprocessable Content.

Read the response

Maintenance resources are returned inside data with:

id, project_id, and the creator and canceller user IDs.
source: manual, api, or system.
status: scheduled, active, completed, or cancelled.
starts_at, ends_at, details, and cancelled_at.
created_at and updated_at.

Resources outside the token's project return 404 Not Found. A mismatched project, missing ability, or insufficient current role returns 403 Forbidden. Maintenance endpoints allow 60 requests per minute per authenticated user.

See API errors, rate limits, and fingerprints for error-handling guidance.