Référence de l’API publique

Référence de l’API publiqueDeux surfaces machine, hors du préfixe /v1 : les battements et les pages de statut. Ce sont les seules d'INOWATCH ouvertes à l'extérieur ; les autres n'ont qu'un appelant légitime, interne à INOVERTIX, et ne sont pas documentées ici.Base : https://messagerie.inovertix.comPOST /api/inowatch/beat/{slug}Enregistre un battement pour la tâche identifiée par {slug}.AuthentificationTrois emplacements acceptés, dans cet ordre :

Emplacement	Exemple	Quand l'utiliser
En-tête dédié	`X-Beat-Key: INOWTC_HB_…`	par défaut
Bearer	`Authorization: Bearer INOWTC_HB_…`	client HTTP qui ne pose que cet en-tête
Paramètre d'URL	`?k=INOWTC_HB_…`	panneau de cron sans shell

La clé n'autorise qu'une chose : dire « j'ai tourné ». C'est ce qui rend le troisième emplacement acceptable — une clé qui donnerait accès à des données, elle, est refusée dans une URL.Paramètres (facultatifs, en query ou en corps JSON)

Paramètre	Type	Effet
`failed`	booléen	la tâche a tourné mais s'est mal terminée. Elle reste comptée comme vivante ; l'interface affiche « dernière exécution en erreur ».
`duration_ms`	entier	durée d'exécution, affichée sur la fiche. Plafonnée à 24 h.

Réponse — 200

json

{
  "ok": true,
  "slug": "sauvegarde-fiavia",
  "next_expected_before": "2026-08-16T02:05:00+00:00"
}

next_expected_before est l'instant au-delà duquel le silence deviendra un retard (intervalle + grâce). Utile pour un tableau de bord tiers.ErreursForme commune à tous les modules de CONTROL : { statusCode, name, message }.

Code	`name`	Cause
401	`missing_api_key`	aucune clé transmise
401	`malformed_api_key`	la valeur n'a pas la forme `INOWTC_HB_…`
401	`wrong_module_key`	clé d'un autre module, ou clé de service interne
401	`invalid_api_key`	clé inconnue ou slug ne correspondant pas à cette clé
403	`site_inactive`	la tâche est suspendue dans CONTROL
429	`rate_limit_exceeded`	plus de 60 battements/minute pour cette tâche

invalid_api_key couvre volontairement deux cas : une clé inventée, et une tâche inexistante. Les distinguer ferait de l'endpoint un annuaire — à partir d'une clé quelconque, on énumérerait les tâches surveillées de CONTROL, donc celles qui ne le sont pas.

Limite de débit60 requêtes par minute et par tâche — pas par IP. Une machine qui héberge dix tâches n'en fait donc pas taire neuf : la limite protège chaque heartbeat séparément.GET /api/inowatch/status/{slug}État public d'une page de statut. Aucune authentification : ce sont nos pages, identifiées par un slug, et destinées à être partagées.Réponse — 200

json

{
  "page": {
    "client_name": "Sora Parfume",
    "slug": "sora-parfume",
    "logo_url": "https://…/logo.png",
    "intro": "État de nos services en temps réel."
  },
  "overall": {
    "state": "up",
    "uptime_month": 99.94,
    "services_count": 3
  },
  "services": [
    {
      "ref": "a1b2c3d4e5f6",
      "name": "Boutique",
      "state": "up",
      "uptime_90d": 99.87,
      "uptime_month": 99.94,
      "latency_ms": null,
      "days": [
        { "date": "2026-05-18", "uptime": 100.0, "down_minutes": 0, "avg_latency_ms": 210 }
      ]
    }
  ],
  "incidents": [
    {
      "service": "Boutique",
      "opened_at": "2026-08-11T14:02:00+00:00",
      "resolved_at": "2026-08-11T14:47:00+00:00",
      "duration_minutes": 45,
      "ongoing": false
    }
  ],
  "updated_at": "2026-08-15T09:31:00+00:00"
}

Ce qui n'y figure JAMAIS

l'URL surveillée — elle révèle souvent une adresse d'administration ;

le code HTTP ou le message d'erreur d'un incident ;

l'identifiant réel d'un moniteur (ref est un condensé opaque et stable) ;

la latence, sauf si le moniteur l'autorise explicitement (latency_ms vaut null sinon).

Un uptime à null sur une journée signifie « aucune mesure ce jour-là », pas « 100 % ». Les deux ne doivent pas être confondus à l'affichage.Erreurs

Code	Cause
404	page inexistante ou désactivée (réponse identique, volontairement)
429	plus de 60 requêtes/minute depuis cette IP

Cache60 secondes côté serveur. Une page de statut est relayée précisément le jour d'une panne, c'est-à-dire le jour où le serveur a autre chose à faire.Exemples

bash

# Battement simple
curl -fsS -X POST 'https://messagerie.inovertix.com/api/inowatch/beat/sauvegarde' \
  -H 'X-Beat-Key: INOWTC_HB_…'

# Battement d'échec, avec durée
curl -fsS -X POST 'https://messagerie.inovertix.com/api/inowatch/beat/sauvegarde?failed=1&duration_ms=8200' \
  -H 'X-Beat-Key: INOWTC_HB_…'

# État public
curl -sS 'https://messagerie.inovertix.com/api/inowatch/status/sora-parfume' | jq '.overall'