Browse the docs

Maintenance windows

Schedule planned work, edit it while it is still scheduled, and move it through its lifecycle.

A window has a status of scheduled, in_progress, completed or canceled. With auto_transition on (the default) it starts and completes itself at the scheduled times; the lifecycle endpoints let you do either early. See the maintenance guide.

List windows

GET/user/maintenances

Newest start first, with affected components under maintenanceComponents.

Needs the dashboard.read permission, or an API key with the matching scope.

Query parameters

workspace_idintegerrequired
The workspace to read from.
page_idinteger
Only windows on this page.
statusstring
One status.
limitintegerdefault 20
Rows per page, up to 50.
offsetintegerdefault 0
Rows to skip.
Request
curl "https://api.statusbee.co/user/maintenances?workspace_id=5&status=scheduled" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "rows": [
      {
        "id": 17,
        "workspace_id": 5,
        "org_id": 5,
        "page_id": 4,
        "title": "Database upgrade",
        "body_md": "Expect read-only mode for up to 20 minutes.",
        "status": "scheduled",
        "scheduled_start": "2026-09-20T02:00:00.000Z",
        "scheduled_end": "2026-09-20T03:00:00.000Z",
        "started_at": null,
        "completed_at": null,
        "auto_transition": true,
        "remind_offsets": [
          1440,
          60
        ],
        "reminded_offsets": [],
        "created_by": 12,
        "created_at": "2026-09-14T09:02:11.000Z",
        "updated_at": "2026-09-14T09:02:11.000Z",
        "maintenanceComponents": [
          {
            "maintenance_id": 17,
            "component_id": 23
          }
        ]
      }
    ],
    "count": 1,
    "limit": 20,
    "offset": 0
  }
}

Schedule a window

POST/user/maintenances

Emits maintenance.scheduled. Reminder offsets already in the past at creation are skipped rather than fired immediately.

Needs the maintenance.manage permission, or an API key with the matching scope.

Body

workspace_idintegerrequired
page_idintegerrequired
titlestringrequired
Up to 200 characters.
scheduled_startstringrequired
ISO 8601.
scheduled_endstringrequired
ISO 8601, after the start.
body_mdstring
Markdown description.
component_idsarray
Components on the page that show Maintenance while the window runs.
remind_offsetsarraydefault [1440, 60]
Minutes before the start to remind subscribers.
auto_transitionbooleandefault true
Start and complete automatically.
notifybooleandefault true
Notify subscribers that it is scheduled.
Request
curl -X POST "https://api.statusbee.co/user/maintenances" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 5,
  "page_id": 4,
  "title": "Database upgrade",
  "body_md": "Expect read-only mode for up to 20 minutes.",
  "scheduled_start": "2026-09-20T02:00:00Z",
  "scheduled_end": "2026-09-20T03:00:00Z",
  "component_ids": [
    23
  ]
}'
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 17,
    "workspace_id": 5,
    "org_id": 5,
    "page_id": 4,
    "title": "Database upgrade",
    "body_md": "Expect read-only mode for up to 20 minutes.",
    "status": "scheduled",
    "scheduled_start": "2026-09-20T02:00:00.000Z",
    "scheduled_end": "2026-09-20T03:00:00.000Z",
    "started_at": null,
    "completed_at": null,
    "auto_transition": true,
    "remind_offsets": [
      1440,
      60
    ],
    "reminded_offsets": [],
    "created_by": 12,
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Edit a scheduled window

PATCH/user/maintenances/:id

Only while status is scheduled; otherwise 409. Changing the start or the offsets recomputes which reminders are still due.

Needs the maintenance.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Window id.

Body

titlestring
body_mdstring
scheduled_startstring
scheduled_endstring
remind_offsetsarray
auto_transitionboolean
Request
curl -X PATCH "https://api.statusbee.co/user/maintenances/17" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduled_end": "2026-09-20T03:30:00Z"
}'
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 17,
    "workspace_id": 5,
    "org_id": 5,
    "page_id": 4,
    "title": "Database upgrade",
    "body_md": "Expect read-only mode for up to 20 minutes.",
    "status": "scheduled",
    "scheduled_start": "2026-09-20T02:00:00.000Z",
    "scheduled_end": "2026-09-20T03:30:00.000Z",
    "started_at": null,
    "completed_at": null,
    "auto_transition": true,
    "remind_offsets": [
      1440,
      60
    ],
    "reminded_offsets": [],
    "created_by": 12,
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Start a window

POST/user/maintenances/:id/start

Sets affected components to Maintenance and emits maintenance.started. 409 MAINTENANCE_STATUS if it is not scheduled; data.status tells you what it is.

Needs the maintenance.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Window id.
Request
curl -X POST "https://api.statusbee.co/user/maintenances/17/start" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 17,
    "workspace_id": 5,
    "org_id": 5,
    "page_id": 4,
    "title": "Database upgrade",
    "body_md": "Expect read-only mode for up to 20 minutes.",
    "status": "in_progress",
    "scheduled_start": "2026-09-20T02:00:00.000Z",
    "scheduled_end": "2026-09-20T03:00:00.000Z",
    "started_at": "2026-09-14T09:02:11.000Z",
    "completed_at": null,
    "auto_transition": true,
    "remind_offsets": [
      1440,
      60
    ],
    "reminded_offsets": [],
    "created_by": 12,
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Complete a window

POST/user/maintenances/:id/complete

Restores components and emits maintenance.completed.

Needs the maintenance.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Window id.
Request
curl -X POST "https://api.statusbee.co/user/maintenances/17/complete" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 17,
    "workspace_id": 5,
    "org_id": 5,
    "page_id": 4,
    "title": "Database upgrade",
    "body_md": "Expect read-only mode for up to 20 minutes.",
    "status": "completed",
    "scheduled_start": "2026-09-20T02:00:00.000Z",
    "scheduled_end": "2026-09-20T03:00:00.000Z",
    "started_at": "2026-09-14T09:02:11.000Z",
    "completed_at": "2026-09-14T09:02:11.000Z",
    "auto_transition": true,
    "remind_offsets": [
      1440,
      60
    ],
    "reminded_offsets": [],
    "created_by": 12,
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}

Cancel a window

POST/user/maintenances/:id/cancel

Emits maintenance.completed with canceled: true. Subscribers are not notified.

Needs the maintenance.manage permission, or an API key with the matching scope.

Path parameters

idintegerrequired
Window id.
Request
curl -X POST "https://api.statusbee.co/user/maintenances/17/cancel" \
  -H "Authorization: Bearer sb_live_…"
Response
{
  "statusCode": 200,
  "error": false,
  "message": null,
  "data": {
    "id": 17,
    "workspace_id": 5,
    "org_id": 5,
    "page_id": 4,
    "title": "Database upgrade",
    "body_md": "Expect read-only mode for up to 20 minutes.",
    "status": "canceled",
    "scheduled_start": "2026-09-20T02:00:00.000Z",
    "scheduled_end": "2026-09-20T03:00:00.000Z",
    "started_at": null,
    "completed_at": null,
    "auto_transition": true,
    "remind_offsets": [
      1440,
      60
    ],
    "reminded_offsets": [],
    "created_by": 12,
    "created_at": "2026-09-14T09:02:11.000Z",
    "updated_at": "2026-09-14T09:02:11.000Z"
  }
}