API de feedback

L’API de feedback enregistre ce qui se trouvait réellement dans un clip : s’il s’agissait d’une intrusion, si cette intrusion était un incident réel, et tout ce que vous souhaitez y joindre. C’est le chemin d’intégration recommandé pour le retour opérateur, en remplacement du endpoint labels pour les intégrateurs.

Signalez ce que vous avez constaté, pas si Gaard avait raison. Vous connaissez généralement la vérité terrain grâce à votre propre traitement des alarmes, alors que juger la sortie de Gaard supposerait de savoir d’abord ce qu’il a conclu. Envoyez intrusion et Gaard en déduit le verdict pour vous (voir Déclaration et verdict dérivé).

Le feedback est en append-only. Chaque envoi crée un nouvel enregistrement ; les corrections sont de nouveaux envois, jamais des modifications. Le feedback que vous publiez est visible par votre équipe dans la vue Feedback de la plateforme, y compris vos métadonnées personnalisées, en pleine fidélité.

Envoyer un feedback

POST /v1/feedback

Le corps combine une petite enveloppe stricte avec tout ce que vous voulez envoyer. Les champs inconnus ne sont pas une erreur : le corps de la requête est conservé mot pour mot et reste disponible pour un traitement ultérieur.

Exemple de requête

{
  "analyse_id": 999001,
  "intrusion": "no",
  "labels": ["person"],
  "comment": "faux positif - reflet de phare",
  "severity": "high",
  "real_incident": false,
  "metadata": {
    "expected_total": 5,
    "plane": "som",
    "lens_diopter": -1.3
  },
  "integrator_custom_block": { "anything": ["goes", "here"] }
}

Champs de l’enveloppe

Champ	Type	Requis	Description
`analyse_id`	number	l’un des deux	Votre référence d’analyse pour la classification.
`id`	string	l’un des deux	L’identifiant de tâche de classification Gaard.
`intrusion`	string	l’un des deux	`yes` ou `no` : ce qui, selon vous, se trouvait réellement dans le clip.
`verdict`	string	l’un des deux	`correct` ou `incorrect`. Facultatif : dérivé de `intrusion` si vous l’omettez.
`labels`	string[]	non	Labels suggérés pour le clip.
`comment`	string	non	Explication en texte libre.
`severity`	string	non	`low`, `medium`, `high` ou `critical`.
`real_incident`	boolean	non	Marque un incident réel confirmé. Alimente le registre des incidents réels de la plateforme. Ne peut pas valoir `true` avec `intrusion: "no"`.
`metadata`	object	non	Contexte clé-valeur plat, affiché dans l’interface de la plateforme.

Au moins l’un de analyse_id ou id est requis. Lorsque c’est possible, Gaard résout l’autre référence ainsi que l’identité du site et de la caméra depuis la tâche de classification.

Au moins l’un de intrusion ou verdict est requis : un commentaire seul ne constitue donc pas un envoi. Envoyer les deux est autorisé : un verdict explicite est stocké tel que vous l’avez envoyé et n’est jamais écrasé par la dérivation.

Déclaration et verdict dérivé

intrusion est votre énoncé de vérité terrain. verdict est un énoncé sur Gaard : si son niveau de risque pour le clip concordait avec le vôtre. Lorsque vous envoyez intrusion sans verdict, Gaard le dérive :

Vous avez déclaré	Niveau de risque Gaard	Verdict dérivé
`yes`	intrusion	`correct`
`yes`	danger	`correct`
`yes`	safe	`incorrect`
`no`	intrusion	`incorrect`
`no`	danger	`incorrect`
`no`	safe	`correct`

Le verdict dérivé est binaire : soit la classification concordait avec vous, soit non. Un niveau de risque danger compte comme une alarme et non comme une nuance, car c’est ainsi que la plateforme le traite : tout ce qui n’est pas safe est transmis, remonté aux opérateurs et examiné. Si la plateforme a agi sur un clip et que vous estimez qu’elle n’aurait pas dû, c’est un échec et il est compté comme tel.

Avant le 19 août 2026, un niveau de risque danger donnait inconclusive. Les lignes stockées ne sont jamais recalculées : un retour envoyé avant cette date conserve donc le verdict qui lui a été attribué, et inconclusive reste une valeur filtrable dans la plateforme. Plus rien ne le produit aujourd’hui. Vous pouvez encore l’envoyer explicitement, mais nous le déconseillons.

Le verdict stocké revient vide lorsque le clip ne peut pas être évalué :

vous l’avez référencé uniquement par analyse_id et aucune tâche de classification n’a été résolue
la tâche appartient à un flux différent de celui de vos identifiants
la tâche existe mais sa classification n’avait pas encore produit de résultat, ce qui arrive lorsque vous envoyez pendant que la classification est en cours

Un verdict vide signifie « non évaluable » : Gaard n’a jamais jugé le clip, il n’y a donc rien avec quoi être ou non d’accord. Ce n’est pas une troisième valeur de verdict, et ce n’est pas la même chose que l’ancien inconclusive. La vue Feedback de la plateforme l’affiche « Non évaluable ».

Votre déclaration est toujours stockée, quel que soit le verdict obtenu.

Métadonnées personnalisées

Les valeurs de metadata sont stockées en chaînes et affichées en panneau clé-valeur sur les détails de la vidéo dans la plateforme :

les chaînes passent sans modification
les nombres et booléens sont convertis en chaînes (5, -1.3, true)
les objets et tableaux imbriqués sont stockés en chaînes JSON
les valeurs null sont ignorées

Garantie sur le payload

Tout ce que vous envoyez, y compris les champs que Gaard ne comprend pas, est conservé octet par octet dans l’enregistrement. Vous n’avez pas besoin d’adapter votre JSON interne à notre schéma pour commencer à envoyer du feedback.

Réponses

Statut	Signification
`200`	Enregistré. Le corps de la réponse est `{ "success": true, "data": { ...enregistrement } }`.
`401` / `403`	Identifiants manquants ou invalides.
`413`	Corps supérieur à 1 Mio.
`422`	`intrusion`/`verdict`/`severity` inconnu, ni `analyse_id` ni `id` présent, ni `intrusion` ni `verdict` présent, ou `real_incident: true` avec `intrusion: "no"`.

Un real_incident: true contradictoire avec intrusion: "no" est rejeté plutôt que corrigé silencieusement, afin que vos analyses ne divergent jamais de ce que vous avez envoyé. Envoyer real_incident: true sans aucun intrusion reste valide.

Exemple de réponse

{
  "success": true,
  "data": {
    "Id": "6a61e46b194b60cccf924696",
    "AnalyseId": 999001,
    "Intrusion": "no",
    "Verdict": "incorrect",
    "Severity": "high",
    "RealIncident": 0,
    "Labels": ["person"],
    "Metadata": { "expected_total": "5", "plane": "som", "lens_diopter": "-1.3" },
    "Payload": "{ ...votre corps de requête, mot pour mot... }"
  }
}

Envois en double

Deux envois identiques créent deux enregistrements, chacun renvoyant 200. C’est voulu : le feedback est un flux de jugements, et plusieurs relecteurs (ou relectures répétées) sont tous conservés.

Authentification

Utilisez la même authentification bearer que le reste de l’API v1 :

Authorization: Bearer <API_KEY>