API

Maintenance

API reference for Maintenance: every handler with its fields and an example.

Last updated:

maintenance: detail

Get maintenance

Returns a single maintenance row by id, including its status, scheduled/actual timestamps, and announcement body, for the maintenance edit screen.

  • Required scope: maintenance:read
  • Endpoint: POST /api/query
Field Type Required Description
id string (uuid) yes

Example request

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:maintenance:detail",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

maintenance: list

List maintenance windows

Returns a filtered, paginated set of maintenance rows, including past and cancelled ones, with their status and scheduled window, for the admin maintenance list.

  • Required scope: maintenance:read
  • Endpoint: POST /api/query
Field Type Required Description
cursor string no Position from nextCursor of the previous page.
limit integer no Rows per page, 50 by default, at most 200.
search string no Full-text search across the searchable fields.
sort string no Field to sort by.
sortDirection “asc” | “desc” no asc or desc.
offset integer no Number of rows to skip. Prefer cursor for paging.
totalCount boolean no Set true to also get total, the number of matching rows.
includeDeleted boolean no Set true to include deleted rows. Only for entities with soft delete.
onlyDeleted boolean no Set true to return only deleted rows. Only for entities with soft delete, not together with includeDeleted.
filter object no One field filter with field, op and value. op is one of eq, ne, lt, gt, lte, gte, in.
filter.field string yes
filter.op “eq” | “ne” | “lt” | “gt” | “lte” | “gte” | “in” yes
filter.value any yes
filters array of object no Several field filters, each with field, op and value. op is one of eq, ne, lt, gt, lte, gte, in.
namedFilter string no Name of a predefined filter of the entity, for example a work queue.
aggregate object no Returns aggregated values instead of rows.
aggregate.groupBy string no
aggregate.measures array of object no

Example request

curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:maintenance:list",
  "payload": {}
}'

Example response

Status: 200

{
  "data": {
    "rows": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "tenantId": "00000000-0000-4000-8000-000000000002",
        "version": 2,
        "insertedAt": "2026-01-15T09:30:00.000Z",
        "modifiedAt": null,
        "insertedById": "00000000-0000-4000-8000-000000000003",
        "modifiedById": null,
        "title": "Database upgrade",
        "body": "Short read-only period while we upgrade the database.",
        "status": "scheduled",
        "scheduledStart": "2026-01-15T09:30:00.000Z",
        "scheduledEnd": "2026-01-15T09:30:00.000Z",
        "startedAt": null,
        "completedAt": null,
        "cancelledAt": null
      }
    ],
    "nextCursor": null
  }
}

maintenance: cancel

Cancel maintenance

Cancels a scheduled or in-progress maintenance window and records the cancellation time.

  • Required scope: maintenance:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes
version number no

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:cancel",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'

maintenance: complete

Complete maintenance

Transitions an in-progress maintenance window to completed and records its actual completion time.

  • Required scope: maintenance:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes
version number no

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:complete",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'

maintenance: schedule

Schedule maintenance

Schedules a new maintenance window with a title, description and time range, optionally linking it to the affected components.

  • Required scope: maintenance:write
  • Endpoint: POST /api/write
Field Type Required Description
title string yes Title
body string yes Body
scheduledStart string (date-time) yes Scheduled Start
scheduledEnd string (date-time) yes Scheduled End
componentIds array of string (uuid) no Affected Components

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:schedule",
  "payload": {
    "title": "Database upgrade",
    "body": "Short read-only period while we upgrade the database.",
    "scheduledStart": "2026-01-15T09:30:00.000Z",
    "scheduledEnd": "2026-01-15T09:30:00.000Z",
    "componentIds": [
      "00000000-0000-4000-8000-000000000001"
    ]
  }
}'

Example response

Status: 200

{
  "isSuccess": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000002"
  }
}

maintenance: start

Start maintenance

Transitions a scheduled maintenance window to in-progress and records its actual start time.

  • Required scope: maintenance:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes
version number no

Example request

curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:start",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'