API

Components

Riferimento API per Components: ogni handler con i suoi campi e un esempio.

Ultimo aggiornamento:

component: detail

Ottenere componente

Restituisce un componente tramite il suo ID, con stato, componente padre, ordine e campi personalizzati.

  • Scope richiesto: components:read
  • Endpoint: POST /api/query
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì

Richiesta di esempio

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

Elencare componenti

Restituisce un elenco filtrato e paginato di componenti, anche quelli nascosti, con stato e raggruppamento.

  • Scope richiesto: components:read
  • Endpoint: POST /api/query
Campo Tipo Obbligatorio Descrizione
cursor string no Posizione da nextCursor della pagina precedente.
limit integer no Righe per pagina, 50 per impostazione predefinita, al massimo 200.
search string no Ricerca full-text nei campi ricercabili.
sort string no Campo per cui ordinare.
sortDirection “asc” | “desc” no asc o desc.
offset integer no Numero di righe da saltare. Per sfogliare è meglio cursor.
totalCount boolean no Con true ricevi anche total, il numero di righe corrispondenti.
includeDeleted boolean no Con true sono incluse le righe eliminate. Solo per entità con eliminazione logica.
onlyDeleted boolean no Con true vengono restituite solo le righe eliminate. Solo per entità con eliminazione logica, non insieme a includeDeleted.
filter object no Un filtro di campo con field, op e value. op è uno tra eq, ne, lt, gt, lte, gte, in.
filter.field string sì
filter.op “eq” | “ne” | “lt” | “gt” | “lte” | “gte” | “in” sì
filter.value any sì
filters array of object no Più filtri di campo, ciascuno con field, op e value. op è uno tra eq, ne, lt, gt, lte, gte, in.
namedFilter string no Nome di un filtro predefinito dell’entità, per esempio una coda di lavoro.
aggregate object no Restituisce valori aggregati invece di righe.
aggregate.groupBy string no
aggregate.measures array of object no

Richiesta di esempio

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": {}
}'

Risposta di esempio

Stato: 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

Creare componente

Crea un nuovo componente della pagina di stato, mostrato con il proprio stato operativo.

  • Scope richiesto: components:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
name string sì Nome
description string no Descrizione
status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no Stato
parentComponentId string no Componente padre
displayOrder integer no Ordine
showOnPage boolean no Pubblico
customFields object no

Richiesta di esempio

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"
  }
}'

Risposta di esempio

Stato: 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

Eliminare componente

Elimina definitivamente un componente. I collegamenti di incidenti e manutenzioni precedenti puntano allora a un componente che non esiste più.

  • Scope richiesto: components:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì

Richiesta di esempio

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

Modificare componente

Modifica i campi di un componente, compreso lo stato operativo visto dai visitatori.

  • Scope richiesto: components:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì
version number sì
changes object sì
changes.name string no Nome
changes.description string | null no Descrizione
changes.status “operational” | “degraded-performance” | “partial-outage” | “major-outage” | “under-maintenance” no Stato
changes.parentComponentId string | null no Componente padre
changes.displayOrder integer no Ordine
changes.showOnPage boolean no Pubblico
changes.customFields object no

Richiesta di esempio

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": {}
    }
  }
}'