Servor. docs
en

API Incidents

Lisez et automatisez vos incidents via l'API Servor — créez des incidents, publiez des mises à jour et résolvez-les avec un jeton incidents:read ou incidents:write.

Lisez vos incidents et pilotez leur automatisation par programme. L'API Incidents est le seul endroit où l'API Servor fait plus que lire : vous pouvez créer des incidents, publier des mises à jour au fil de l'eau et les résoudre une fois le problème corrigé. C'est l'outil idéal pour brancher votre propre système d'alerte ou vos runbooks sur Servor.

La lecture des incidents requiert le scope incidents:read. La création d'incidents et la publication de mises à jour requièrent incidents:write.

get/v1/incidentsScope: incidents:read

List incidents

Exemple de requête

curl https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

[
  {
    "id": "uuid",
    "title": "API degraded",
    "status": "investigating",
    "impact": "major",
    "statusPageId": "uuid",
    "isMaintenance": false,
    "startedAt": "2026-08-20T10:00:00.000Z",
    "resolvedAt": null,
    "createdAt": "2026-08-20T10:00:00.000Z"
  }
]
post/v1/incidentsScope: incidents:write

Create an incident

Corps de la requête

  • titlestringrequis

    Short incident title.

  • statusinvestigating | identified | monitoring | resolvedrequis
  • impactnone | minor | major | criticalrequis
  • messagestringrequis

    First update posted with the incident.

  • statusPageIduuidoptionnel

    Attach the incident to a status page.

  • componentIdsuuid[]optionnel

    Affected components.

Exemple de requête

curl -X POST https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"<string>","status":"<investigating | identified | monitoring | resolved>","impact":"<none | minor | major | critical>","message":"<string>"}'

Exemple de réponse

{
  "id": "uuid",
  "title": "API degraded",
  "status": "investigating"
}
get/v1/incidents/{id}Scope: incidents:read

Get an incident with its timeline

Paramètres

  • iduuidpath · requis

    The incident id.

Exemple de requête

curl https://api.servor.app/v1/incidents/:id \
  -H "Authorization: Bearer sv_live_..."

Exemple de réponse

{
  "id": "uuid",
  "title": "API degraded",
  "status": "identified",
  "impact": "major",
  "statusPageId": "uuid",
  "isMaintenance": false,
  "startedAt": "2026-08-20T10:00:00.000Z",
  "resolvedAt": null,
  "createdAt": "2026-08-20T10:00:00.000Z",
  "updates": [
    {
      "id": "uuid",
      "status": "investigating",
      "message": "Looking into it.",
      "createdAt": "2026-08-20T10:05:00.000Z"
    }
  ]
}
post/v1/incidents/{id}/updatesScope: incidents:write

Post an update (resolve with status=resolved)

Paramètres

  • iduuidpath · requis

    The incident id.

Corps de la requête

  • statusinvestigating | identified | monitoring | resolvedrequis

    Use "resolved" to close the incident.

  • messagestringrequis
  • notifySubscribersbooleanoptionnel

    Email/webhook subscribers (default true).

Exemple de requête

curl -X POST https://api.servor.app/v1/incidents/:id/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"<investigating | identified | monitoring | resolved>","message":"<string>"}'

Exemple de réponse

{
  "id": "uuid",
  "status": "resolved"
}

Lecture ou écriture

  • incidents:read — lister les incidents, lire un incident et sa chronologie de mises à jour. Suffisant pour des tableaux de bord, des exports ou une copie dans vos propres outils.
  • incidents:write — créer des incidents et publier des mises à jour (y compris celle qui les résout). Ne l'accordez qu'aux jetons qui écrivent réellement.

Moindre privilège

Si un jeton ne fait qu'afficher des incidents, donnez-lui uniquement incidents:read. Gardez l'accès en écriture sur des jetons séparés, révocables indépendamment. Voir les scopes.

Créer un incident

Un incident comporte un titre, un statut, un niveau d'impact et un message d'ouverture. Vous pouvez éventuellement le rattacher à une page de statut et à ses composants pour qu'il s'affiche publiquement et notifie les abonnés.

curl -X POST https://api.servor.app/v1/incidents \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Taux d'\''erreur API élevé",
    "status": "investigating",
    "impact": "major",
    "message": "Nous enquêtons sur un pic de réponses 5xx."
  }'

La réponse contient l'id du nouvel incident, que vous utiliserez pour publier des mises à jour.

Publier des mises à jour et résoudre

À mesure que la situation évolue, publiez des mises à jour sur le même incident. Chaque mise à jour porte un status et un message ; les deux sont ajoutés à la chronologie publique et notifient les abonnés de la page de statut rattachée.

curl -X POST https://api.servor.app/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "monitoring",
    "message": "Un correctif a été déployé. Nous surveillons le taux d'\''erreur."
  }'

Pour résoudre un incident, publiez une mise à jour dont le status vaut resolved :

curl -X POST https://api.servor.app/v1/incidents/inc_123/updates \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "message": "Le taux d'\''erreur est revenu à la normale. Incident résolu."
  }'

Résoudre, c'est mettre à jour

Il n'existe pas d'appel « clôturer » distinct. Un incident se résout en publiant une mise à jour dont le statut est resolved — la chronologie conserve tout l'historique.

Incidents automatiques

Les incidents n'ont pas à être créés à la main. Servor peut en ouvrir un automatiquement lorsqu'un moniteur bascule en down. Voir les incidents automatiques pour le fonctionnement de la détection et signaler un incident pour le flux manuel dans le tableau de bord — signaler un incident dans Servor. Quelle que soit la façon dont un incident est ouvert, vous pouvez y publier des mises à jour et le résoudre via l'API.

Une automatisation type

Détecter le problème

Votre propre système d'alerte (ou un moniteur) détecte une anomalie.

Ouvrir un incident

POST /v1/incidents avec un titre, status: "investigating" et un niveau d'impact, rattaché à votre page de statut.

Tenir informé

POST /v1/incidents/{id}/updates à chaque étape — identifié, en surveillance, etc.

Résoudre

Publiez une dernière mise à jour avec status: "resolved" une fois le problème corrigé.

Remarques

  • Les mises à jour d'incident sont publiques sur la page de statut rattachée et notifient les abonnés — rédigez des messages que vos utilisateurs liront.
  • Un 403 signifie que votre jeton n'a pas le scope requis pour l'action : incidents:read pour lire, incidents:write pour créer ou mettre à jour. Voir les erreurs.
  • Un 422 signifie que le payload a échoué à la validation (par exemple un title manquant ou un status inconnu) ; le champ details de la réponse indique lequel.

Voir aussi

API Pages de statutLisez les pages et leurs incidents.API MoniteursRécupérez les données de moniteur derrière un incident.Mettre à jour et résoudreLe flux dans le tableau de bord.ScopesAccès en lecture ou en écriture.
PrécédentMoniteursSuivantPages de statut