API Groupes de monitors

URL de base : https://api.okstatus.eu/api/v1/monitor-groups — chaque requête nécessite un header Authorization: Bearer oks_live_..., voir Authentification.

Un groupe est un dossier de la page Monitors. Deux règles expliquent les endpoints ci-dessous :

• Un monitor appartient à un seul groupe au plus. Le placer dans un groupe le retire du précédent.
• Un groupe peut porter des canaux d’alerte. Un monitor qui rejoint le groupe les reçoit ; les monitors déjà dans le groupe ne sont pas touchés quand les canaux du groupe changent.

Lister les groupes

GET /api/v1/monitor-groups

Retourne tous les groupes, dans l’ordre du tableau de bord, avec les identifiants de leurs monitors.

{
  "data": [
    {
      "id": "7b1e…",
      "name": "Paiement",
      "description": "Tout le parcours de commande",
      "color": "aurora",
      "tags": ["prod"],
      "alertChannelIds": ["3f6e…"],
      "monitorIds": ["a41c…", "c9d2…"],
      "paused": false,
      "muted": false
    }
  ]
}

paused et muted indiquent si le groupe entier a été mis en pause ou en sourdine depuis le tableau de bord ; ils sont en lecture seule ici. Pour mettre des monitors en pause par l’API, faites un PATCH sur chaque monitor.

Créer un groupe

POST /api/v1/monitor-groups
Content-Type: application/json

Champ	Type	Requis	Description
name	string	✅	Nom du groupe (1 à 255 caractères)
description	string		Texte libre affiché sous le nom
color	string		Une couleur de la palette du tableau de bord, par sa clé — telle que renvoyée pour un groupe existant
tags	string[]		Jusqu’à 10 tags, pour le groupe lui-même (ils ne sont pas copiés sur ses monitors)
alertChannelIds	string[]		Canaux rattachés à chaque monitor qui rejoint le groupe
monitorIds	string[]		Les monitors du groupe

Retourne 201 avec { "data": Groupe }. Si l’un des monitorIds n’est pas un monitor de votre organisation, la requête échoue avec 404 NOT_FOUND et aucun groupe n’est créé.

Récupérer / modifier / supprimer un groupe

GET    /api/v1/monitor-groups/:id
PATCH  /api/v1/monitor-groups/:id
DELETE /api/v1/monitor-groups/:id

PATCH accepte les mêmes champs que la création, tous optionnels. monitorIds est la composition complète du groupe : les monitors absents de la liste quittent le groupe, et [] le vide.

curl -X PATCH https://api.okstatus.eu/api/v1/monitor-groups/$GROUP_ID \
  -H "Authorization: Bearer $OKSTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "monitorIds": ["a41c…", "c9d2…", "e07f…"] }'

DELETE supprime le groupe seulement — ses monitors sont conservés et reviennent dans la liste sans groupe. Il retourne { "data": { "deleted": true } }.

Erreurs

404 NOT_FOUND si le groupe, ou un monitor cité dans monitorIds, n’existe pas dans votre organisation. Voir Authentification pour le format d’erreur commun et les limites de débit.