PATCH /maintenances/{id}

Edit maintenance (only allowed before actual_start_at is set)

Request body

{
  "title": "string",
  "scheduled_start_at": "2026-01-01T00:00:00.000Z",
  "scheduled_end_at": "2026-01-01T00:00:00.000Z",
  "affected_services": [
    "string"
  ]
}

Example request

curl -X PATCH "/api/v1/maintenances/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"title":"string","scheduled_start_at":"2026-01-01T00:00:00.000Z","scheduled_end_at":"2026-01-01T00:00:00.000Z","affected_services":["string"]}"

Responses

200: ok

{
  "id": "string",
  "title": "string",
  "type": "Incident",
  "severity": null,
  "state": "draft",
  "published_at": null,
  "resolved_at": null,
  "scheduled_start_at": null,
  "scheduled_end_at": null,
  "actual_start_at": null,
  "actual_end_at": null,
  "canceled_at": null,
  "postmortem_url": null,
  "affected_services": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "visible_to_customer_ids": [
    "string"
  ],
  "messages": [
    {
      "id": "string",
      "type": "Investigating",
      "description": "string",
      "date": "2026-01-01T00:00:00.000Z"
    }
  ],
  "created_at": "2026-01-01T00:00:00.000Z"
}

400: invalid request

One of:

invalid_json — the body is not valid JSON.
invalid_window — the timestamps are not valid ISO 8601, or the end is not after the start.

401: missing or invalid bearer token

title: unauthenticated. No bearer token was sent, or the key is invalid or revoked. detail distinguishes the two.

403: missing required scope

title: forbidden. The key is valid but does not carry write:maintenances.

404: not found

title: not_found. No maintenance window with that id is available to this key. A window owned by another organisation returns the same response, so a 404 does not confirm that the id is unused.

409: conflicting state

title: already_started. The window has already started and can no longer be edited.

429: rate limit exceeded

title: rate_limited. A burst or daily limit was exceeded; detail names which. The body carries retry_after in seconds.

500: internal error

title: internal_error. An unhandled server error. Safe to retry.

Every error is an RFC 7807 problem detail served as application/problem+json:

{
  "type": "https://observer.example/problems/forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:maintenances"
}

Branch on title, not on detail. See Errors and status codes for the full catalogue and the rate-limit headers.

Was this page helpful?