API

Maintenance

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

Ultimo aggiornamento:

maintenance: detail

Ottenere manutenzione

Restituisce una manutenzione tramite il suo ID, con stato, orari previsti ed effettivi e testo dell’annuncio.

  • Scope richiesto: maintenance: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:maintenance:detail",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}'

maintenance: list

Elencare manutenzioni

Restituisce un elenco filtrato e paginato di manutenzioni, anche quelle passate e annullate, con stato e finestra prevista.

  • Scope richiesto: maintenance: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:maintenance:list",
  "payload": {}
}'

Risposta di esempio

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

Annullare manutenzione

Annulla una manutenzione pianificata o in corso e registra l’ora dell’annullamento.

  • Scope richiesto: maintenance:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì
version number 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:maintenance:cancel",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'

maintenance: complete

Completare manutenzione

Imposta una manutenzione in corso come completata e registra l’ora effettiva di conclusione.

  • Scope richiesto: maintenance:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì
version number 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:maintenance:complete",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'

maintenance: schedule

Pianificare manutenzione

Pianifica una nuova finestra di manutenzione con titolo, descrizione e periodo e, se richiesto, la collega ai componenti interessati.

  • Scope richiesto: maintenance:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
title string sì Titolo
body string sì Descrizione
scheduledStart string (date-time) sì Inizio previsto
scheduledEnd string (date-time) sì Fine prevista
componentIds array of string (uuid) no Componenti interessati

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

Risposta di esempio

Stato: 200

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

maintenance: start

Avviare manutenzione

Porta una manutenzione pianificata a in corso e registra l’ora effettiva di inizio.

  • Scope richiesto: maintenance:write
  • Endpoint: POST /api/write
Campo Tipo Obbligatorio Descrizione
id string (uuid) sì
version number 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:maintenance:start",
  "payload": {
    "id": "00000000-0000-4000-8000-000000000001",
    "version": 1
  }
}'