API

Components

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

Last updated:

component: detail

Get component

Returns a single component row by id, including its status, parent component, display order, and custom fields, for the component edit screen.

  • Required scope: components: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:component:detail",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

component: list

List components

Returns a filtered, paginated set of component rows, including hidden ones, with their status and parent grouping, for the admin component list.

  • Required scope: components: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:component:list",
  "payload": {}
}'

Example response

Status: 200

{
  "data": {
    "rows": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "tenantId": "00000000-0000-4000-8000-000000000002",
        "version": 1,
        "insertedAt": "2026-01-15T09:30:00.000Z",
        "modifiedAt": null,
        "insertedById": "00000000-0000-4000-8000-000000000003",
        "modifiedById": null,
        "name": "API",
        "description": null,
        "status": "operational",
        "parentComponentId": null,
        "displayOrder": 0,
        "showOnPage": true,
        "customFields": {}
      }
    ],
    "nextCursor": null
  }
}

component: create

Create component

Creates a new status-page component that is listed with its own operational status.

  • Required scope: components:write
  • Endpoint: POST /api/write
Field Type Required Description
name string yes Name
description string no Description
status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no Status
parentComponentId string no Parent Component
displayOrder integer no Display Order
showOnPage boolean no Public
customFields object 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:component:create",
  "payload": {
    "name": "API"
  }
}'

Example response

Status: 200

{
  "isSuccess": true,
  "data": {
    "kind": "save",
    "id": "00000000-0000-4000-8000-000000000001",
    "data": {
      "id": "00000000-0000-4000-8000-000000000001",
      "tenantId": "00000000-0000-4000-8000-000000000002",
      "version": 1,
      "insertedAt": "2026-01-15T09:30:00.000Z",
      "modifiedAt": null,
      "insertedById": "00000000-0000-4000-8000-000000000003",
      "modifiedById": null,
      "name": "API",
      "description": null,
      "status": "operational",
      "parentComponentId": null,
      "displayOrder": 0,
      "showOnPage": true,
      "customFields": {}
    },
    "changes": {
      "name": "API",
      "status": "operational",
      "displayOrder": 0,
      "showOnPage": true
    },
    "previous": {},
    "isNew": true,
    "entityName": "component"
  }
}

component: delete

Delete component

Permanently deletes a status-page component, leaving any historical incident and maintenance links pointing at a component that no longer exists.

  • Required scope: components:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes

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:component:delete",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

component: update

Update component

Updates a status-page component’s fields, including flipping the operational status shown to visitors.

  • Required scope: components:write
  • Endpoint: POST /api/write
Field Type Required Description
id string (uuid) yes
version number yes
changes object yes
changes.name string no Name
changes.description string | null no Description
changes.status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no Status
changes.parentComponentId string | null no Parent Component
changes.displayOrder integer no Display Order
changes.showOnPage boolean no Public
changes.customFields object 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:component:update",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1,
    "changes": {
      "name": "text",
      "description": "text",
      "status": "operational",
      "parentComponentId": "text",
      "displayOrder": 1,
      "showOnPage": true,
      "customFields": {}
    }
  }
}'