API

Flussi di lavoro

Aprire un incidente, pianificare una manutenzione, impostare lo stato di un componente e creare un monitor, passo dopo passo con curl.

Ultimo aggiornamento:

Incidente: aprire, aggiornare, chiudere

Un incidente attraversa tre chiamate. Tutte richiedono lo scope incidents con permesso di scrittura.

  1. incident:open apre l’incidente con un titolo, un primo testo e una gravità (minor, major o critical, se omessa minor). Con componentIds colleghi i componenti interessati. La risposta contiene il nuovo ID in data.id.
  2. incident:post-update aggiunge un aggiornamento. Con newStatus imposti lo stato: investigating, identified o monitoring.
  3. incident:resolve chiude l’incidente con un testo finale.
shellAprire un incidente
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:open",
  "payload": {
    "title": "Elevated API latency",
    "body": "We are investigating elevated response times.",
    "severity": "major",
    "componentIds": [
      "<component-id>"
    ]
  }
}'
shellPubblicare un aggiornamento con un nuovo stato
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:post-update",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "A slow database query is the cause. A fix is rolling out.",
    "newStatus": "identified"
  }
}'
shellChiudere un incidente
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:incident:resolve",
  "payload": {
    "incidentId": "<incident-id>",
    "body": "Response times are back to normal."
  }
}'

Manutenzione: pianificare, avviare, completare o annullare

Le manutenzioni richiedono lo scope maintenance con permesso di scrittura. maintenance:schedule crea la finestra, con inizio e fine come timestamp ISO 8601. La risposta contiene l’ID in data.id.

shellPianificare una manutenzione
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:schedule",
  "payload": {
    "title": "Database upgrade",
    "body": "The API is read-only during the upgrade.",
    "scheduledStart": "2026-11-10T02:00:00Z",
    "scheduledEnd": "2026-11-10T03:00:00Z",
    "componentIds": [
      "<component-id>"
    ]
  }
}'

Poi gestisci la manutenzione con maintenance:start, maintenance:complete o maintenance:cancel. Tutte e tre si aspettano l’id. La version è facoltativa: se la invii, leggila da maintenance:detail con l’id. Se la versione è obsoleta, l’API rifiuta la chiamata con 409 e il codice version_conflict.

shellAvviare una manutenzione
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:start",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellCompletare una manutenzione
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:complete",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'
shellAnnullare una manutenzione pianificata
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:maintenance:cancel",
  "payload": {
    "id": "<maintenance-id>",
    "version": 1
  }
}'

L’API rifiuta le transizioni non valide, per esempio avviare una manutenzione già completata.

Componente: creare e impostare lo stato

I componenti richiedono lo scope components con permesso di scrittura. component:create crea un componente e restituisce il suo ID in data.id. Un nuovo componente parte con operational.

shellCreare un componente
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:create",
  "payload": {
    "name": "API",
    "description": "Public HTTP API"
  }
}'

Lo stato si modifica con component:update. Oltre a id e alle modifiche in changes, la chiamata richiede la version attuale del componente. La ottieni con component:detail e l’id. Dopo la creazione vale 1 e aumenta di uno a ogni modifica. Con una version obsoleta l’API rifiuta la modifica.

shellImpostare un componente su interruzione grave
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:component:update",
  "payload": {
    "id": "<component-id>",
    "version": 1,
    "changes": {
      "status": "major-outage"
    }
  }
}'
operational
Funziona normalmente.
degraded-performance
Limitato, per esempio lento.
partial-outage
Interruzione parziale.
major-outage
Interruzione grave.
under-maintenance
In manutenzione.

Così una pipeline di deploy può impostare un componente su under-maintenance prima del rilascio e poi di nuovo su operational.

Monitor: creare e controllare subito

I monitor richiedono lo scope monitors con permesso di scrittura. monitor:create crea un monitor di disponibilità. kind sceglie il tipo di controllo: http, keyword, ssl-expiry, tcp-port o heartbeat. L’intervallo in intervalSeconds è una stringa con uno di questi valori: "60", "300", "600" o "1800". Con componentId colleghi un componente che passa automaticamente a interruzione grave in caso di guasto.

shellCreare un monitor HTTP con un componente collegato
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:create",
  "payload": {
    "name": "API health",
    "kind": "http",
    "url": "https://api.example.com/health",
    "intervalSeconds": "300",
    "componentId": "<component-id>",
    "enabled": true
  }
}'

monitor:check-now controlla subito un monitor e restituisce il risultato in data.up. La chiamata salva solo un punto di misura. Componenti, incidenti e notifiche vengono modificati solo dal controllo regolare.

shellControllare subito un monitor
curl -X POST https://status.example.com/api/write \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:write:monitor:check-now",
  "payload": {
    "monitorId": "<monitor-id>"
  }
}'

Leggere un record: detail

Oltre agli elenchi, ogni scope con accesso in lettura offre una chiamata :detail che restituisce un record in base al suo id. Restituisce anche la version attuale di cui le modifiche hanno bisogno.

shellLeggere un incidente
curl -X POST https://status.example.com/api/query \
  -H "Authorization: Bearer kpat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "publicstatus:query:incident:detail",
  "payload": {
    "id": "<incident-id>"
  }
}'