API

Parcours

Ouvrir un incident, planifier une maintenance, changer le statut d'un composant et créer un moniteur, pas à pas avec curl.

Dernière mise à jour :

Incident : ouvrir, mettre à jour, clôturer

Un incident passe par trois appels. Tous nécessitent le scope incidents avec droit d’écriture.

  1. incident:open ouvre l’incident avec un titre, un premier texte et une gravité (minor, major ou critical, minor par défaut). Avec componentIds, vous rattachez les composants concernés. La réponse contient le nouvel ID dans data.id.
  2. incident:post-update ajoute une mise à jour. Avec newStatus, vous définissez l’état : investigating, identified ou monitoring.
  3. incident:resolve clôture l’incident avec un dernier texte.
shellOuvrir un incident
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>"
    ]
  }
}'
shellPublier une mise à jour avec un nouvel état
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"
  }
}'
shellClôturer un incident
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."
  }
}'

Maintenance : planifier, démarrer, terminer ou annuler

Les maintenances nécessitent le scope maintenance avec droit d’écriture. maintenance:schedule crée la fenêtre, avec début et fin sous forme d’horodatages ISO 8601. La réponse contient l’ID dans data.id.

shellPlanifier une maintenance
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>"
    ]
  }
}'

Ensuite, vous pilotez la maintenance avec maintenance:start, maintenance:complete ou maintenance:cancel. Les trois attendent l’id. La version est facultative : si vous l’envoyez, lisez-la dans maintenance:detail avec l’id. Si la version est périmée, l’API rejette l’appel avec 409 et le code version_conflict.

shellDémarrer une maintenance
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
  }
}'
shellTerminer une maintenance
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
  }
}'
shellAnnuler une maintenance planifiée
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 refuse les transitions invalides, par exemple démarrer une maintenance déjà terminée.

Composant : créer et définir le statut

Les composants nécessitent le scope components avec droit d’écriture. component:create crée un composant et renvoie son ID dans data.id. Un nouveau composant démarre à operational.

shellCréer un composant
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"
  }
}'

Vous modifiez le statut avec component:update. Outre id et les modifications dans changes, l’appel exige la version actuelle du composant. Vous l’obtenez avec component:detail et l’id. Après la création, elle vaut 1 et augmente de un à chaque modification. Avec une version périmée, l’API refuse la modification.

shellPasser un composant en panne majeure
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
Fonctionne normalement.
degraded-performance
Limité, par exemple lent.
partial-outage
Panne partielle.
major-outage
Panne majeure.
under-maintenance
En maintenance.

Ainsi, un pipeline de déploiement peut passer un composant à under-maintenance avant le déploiement, puis le remettre à operational ensuite.

Moniteur : créer et vérifier immédiatement

Les moniteurs nécessitent le scope monitors avec droit d’écriture. monitor:create crée un moniteur de disponibilité. kind choisit le type de vérification : http, keyword, ssl-expiry, tcp-port ou heartbeat. L’intervalle dans intervalSeconds est une chaîne contenant l’une de ces valeurs : "60", "300", "600" ou "1800". Avec componentId, vous rattachez un composant qui passe automatiquement en panne majeure en cas d’échec.

shellCréer un moniteur HTTP avec un composant rattaché
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 vérifie un moniteur immédiatement et renvoie le résultat dans data.up. L’appel n’enregistre qu’un point de mesure. Les composants, les incidents et les notifications ne sont modifiés que par la vérification régulière.

shellVérifier un moniteur immédiatement
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>"
  }
}'

Lire un enregistrement : detail

En plus des listes, chaque scope avec accès en lecture propose un appel :detail qui renvoie un enregistrement d’après son id. Il renvoie aussi la version actuelle dont les modifications ont besoin.

shellLire un incident
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>"
  }
}'