API Monitors

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

Lister les monitors

GET /api/v1/monitors?page=1&per_page=50

Retourne une liste paginée limitée à votre organisation (per_page jusqu’à 100).

Réponse

{
  "monitors": [
    {
      "id": "...",
      "name": "...",
      "url": "...",
      "type": "http",
      "interval": 60,
      "status": "active",
      "tags": ["prod"]
    }
  ],
  "total": 12,
  "page": 1,
  "perPage": 50,
  "pages": 1
}

Créer un monitor

POST /api/v1/monitors
Content-Type: application/json

Champ	Type	Requis	Description
name	string	✅	Nom du monitor (1 à 100 caractères)
url	string	✅	La cible : une URL http(s):// pour http et llm, un hôte pour ping, tcp et dns (example.com), une URL de connexion pour les bases — voir chaque type de monitor
type	enum		http, tcp, ping, dns, grpc, llm, push, group, postgres, mysql, mongodb, smtp, imap ou redis — http par défaut
interval	number		Secondes entre les vérifications, min 30 — 60 par défaut. Le plancher de votre plan s’applique (300 s en Free, 60 s en Pro)
regions	string[]		Codes de région, de 1 à 5 — ["fr-dc3"] par défaut. Voir Régions
acceptedStatusCodes	string[]		http : codes ou plages comptés comme disponibles, ex. ["200-299", "301"] — ["200-299"] par défaut
tags	string[]		Jusqu’à 5 tags de 30 caractères. Enregistrés en minuscules si votre organisation l’a choisi dans Paramètres → Tags
keyword	string		http : texte que le corps de la réponse doit contenir
followRedirects	boolean		http : suivre les redirections 3xx — true par défaut. Avec false, c’est la réponse de redirection elle-même qui est jugée
httpMethod	enum		http : GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS
httpHeaders	object		http : en-têtes de la requête. Jamais renvoyés : relire le monitor donne "***"
httpBody	string		http : corps de la requête, avec httpBodyEncoding = json, form, xml ou text
ignoreTls	boolean		http : accepter un certificat invalide ou auto-signé
port	number		tcp : port de connexion
dnsRecordType	enum		dns : A, AAAA, CNAME, MX, NS, TXT, SOA, CAA ou SRV
dnsExpectedValue	string		dns : valeur que la réponse doit contenir
dnsServer	string		dns : résolveur à interroger à la place de celui par défaut
retries	number		Vérifications en échec consécutives tolérées avant que le monitor soit indisponible (0 à 5) — 1 par défaut
severity3xx	enum		http : une redirection non acceptée compte comme degraded (par défaut) ou down
latencyThresholdMs	integer		Temps de réponse (50–60000 ms) au-delà duquel le monitor passe degraded et alerte, après max(2, retries + 1) checks lents d’affilée ; null le désactive. Voir Alertes de temps de réponse
latencyPublic	boolean		false garde la lenteur hors des pages de statut publiques (true par défaut)
latencyAnomaly	boolean		Alerte quand le temps de réponse sort de sa plage habituelle apprise (Max et Enterprise, 7 jours d’apprentissage ; refusé en 403 sous Max). Voir Alertes de temps de réponse
sloTarget	number		Objectif SLO en pourcentage sur 30 jours glissants (50 à 99,999, par ex. 99.9) ; null le retire. Max et Enterprise, refusé en 403 en dessous. Voir SLO et budget d’erreur
keywordInvert	boolean		http : le monitor est indisponible quand keyword est trouvé
jsonPath, jsonOperator, jsonExpectedValue			http : assertion sur une réponse JSON (==, !=, >, <, >=, <=, contains). Non combinable avec keyword
basicAuthUser / basicAuthPass	string		Basic auth, et le couple d’identifiants des monitors base de données, SMTP, IMAP et Redis. Stockés chiffrés
authConfig	object		Authentification autre que Basic — voir ci-dessous
dbQuery	string		postgres, mysql, mongodb : requête exécutée à chaque vérification
gracePeriod	number		push : secondes sans ping avant que le monitor soit indisponible. La réponse porte le pushUrl à appeler
childMonitorIds	string[]		group : les monitors qu’il agrège
llmProvider, llmApiKey, llmConfig			llm : voir la référence interactive

Retourne 201 avec { "data": Monitor }.

Un monitor est toujours créé actif et avec ses alertes : pour le mettre en pause ou en sourdine, utilisez un PATCH.

Authentification du point d’accès surveillé

authConfig porte une méthode, discriminée par type (référence complète : Authentification) :

{ "type": "bearer", "token": "…" }
{ "type": "apikey", "in": "header", "name": "X-API-Key", "value": "…" }
{ "type": "apikey", "in": "query", "name": "api_key", "value": "…" }
{ "type": "cookie", "cookie": "session=…; csrf=…" }
{ "type": "oauth2", "tokenUrl": "https://login.example.com/token", "clientId": "…", "clientSecret": "…", "scope": "…", "audience": "…", "authStyle": "basic" }
{ "type": "mtls", "cert": "-----BEGIN CERTIFICATE-----…", "key": "-----BEGIN PRIVATE KEY-----…", "ca": "…" }

Relire un monitor renvoie la méthode et ses réglages non sensibles, chaque secret étant remplacé par "***". Renvoyer ce masque dans un PATCH conserve la valeur enregistrée — c’est ce qui permet de faire un aller-retour GET puis PATCH sans effacer les identifiants. "authConfig": null supprime l’authentification.

Récupérer / modifier / supprimer un monitor

GET    /api/v1/monitors/:id
PATCH  /api/v1/monitors/:id
DELETE /api/v1/monitors/:id

PATCH accepte les champs de la création sauf type (tous optionnels — seuls les champs envoyés changent), plus :

Champ	Type	Description
status	enum	"paused" arrête les vérifications, "active" les relance
isMuted	boolean	true coupe les alertes pendant que les vérifications continuent

Pour retirer une valeur, envoyez null : "keyword": null, "dnsExpectedValue": null, "port": null, "authConfig": null, "basicAuthUser": null. "tags": [] retire tous les tags.

curl -X PATCH https://api.okstatus.eu/api/v1/monitors/$ID \
  -H "Authorization: Bearer $OKSTATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused", "tags": ["prod", "paiement"], "keyword": null }'

DELETE retourne { "data": { "deleted": true } }.

Canaux d’alerte d’un monitor

GET /api/v1/monitors/:id/alert-channels
PUT /api/v1/monitors/:id/alert-channels

GET retourne les identifiants des canaux rattachés au monitor :

{ "data": { "channelIds": ["3f6e2b1a-...", "9c1d4e7f-..."] } }

PUT remplace cet ensemble — une liste vide détache tous les canaux :

{ "channelIds": ["3f6e2b1a-..."] }

Les identifiants sont ceux de GET /api/v1/alert-channels. Un identifiant qui n’est pas un canal de votre organisation est refusé avec 404 NOT_FOUND, et rien n’est modifié. Un canal qui reste rattaché garde ses réglages propres au monitor (les types d’alerte qu’il reçoit).

Régions et agents privés

regions accepte les codes des régions publiques (voir Régions et intervalles) et, sur les plans qui incluent les agents privés :

• "private" — n’importe lequel de vos agents privés exécute la vérification ;
• "private:<id de l'agent>" — cet agent seulement.

GET /api/v1/private-agents

liste vos agents, chacun avec la valeur region à utiliser :

{
  "data": [
    {
      "id": "5a0c…",
      "name": "dc-paris",
      "site": "Paris",
      "region": "private:5a0c…",
      "status": "up",
      "suspended": false,
      "version": "1.0.0",
      "hostname": "probe-1",
      "platform": "linux/amd64",
      "lastHeartbeatAt": "2026-10-10T07:00:00.000Z"
    }
  ],
  "meta": { "eligible": true, "limit": 5, "latestVersion": "1.0.0" }
}

La liste est en lecture seule : un agent s’enrôle depuis le tableau de bord, parce que l’enrôlement remet un identifiant secret. Les jetons d’enrôlement ne sont jamais renvoyés.

Résultats de checks et uptime

GET /api/v1/monitors/:id/checks?page=1&per_page=50
GET /api/v1/monitors/:id/uptime?range=24h

SLO et budget d’erreur

GET /api/v1/slos?status=at_risk
GET /api/v1/monitors/:id/slo?target=99.9

GET /slos liste tous les SLO de l’organisation, monitors et groupes, le pire en premier : kind (monitor ou group), id, name, target, budgetMinutes, consumedMinutes, remainingMinutes, remainingPercent, availability30d, incidents (pannes dans la fenêtre), status (ok, at_risk, exhausted) et exhaustsAt (date d’épuisement au rythme des 7 derniers jours, ou null). status filtre la liste.

GET /monitors/:id/slo renvoie les mêmes chiffres pour un monitor, plus series (le budget restant sur les 30 derniers jours). target prévisualise un objectif sur un monitor qui n’en a pas. Les deux répondent 403 sous Max. Voir SLO et budget d’erreur.

Erreurs

404 NOT_FOUND si le monitor n’existe pas dans votre organisation. Quand une création ou une modification est refusée, l’erreur en donne la raison — par exemple :

Code	Signification
VALIDATION_ERROR	Un champ est invalide ; message le nomme
PLAN_LIMIT_REACHED	Le nombre de monitors de votre plan est atteint
PLAN_INTERVAL_TOO_LOW	L’intervalle est sous le minimum de votre plan
PLAN_REGION_NOT_ALLOWED	Une région n’est pas incluse dans votre plan
PLAN_REGIONS_PER_MONITOR	Trop de régions pour un monitor sur votre plan
INVALID_URL	La cible est une adresse privée ou réservée
UPSTREAM_ERROR	Le moteur de monitoring a échoué sans donner de raison

Voir Authentification pour le format d’erreur commun et les limites de débit.

Limites par plan

Plan	Monitors max	Intervalle min	Régions par monitor
Free	5	300s	2
Pro	20	60s	3
Max	80	30s	5
Enterprise	500 (plus sur demande)	30s	5

Les limites s’appliquent à la création : une organisation déjà au-dessus d’une limite abaissée garde ce qu’elle a, elle ne peut simplement plus en ajouter.