---

title: "API Annotations de graphique" description: "Créez des annotations de déploiement / version / campagne qui se superposent à chaque graphique temporel Zenovay et alimentent le triage des incidents de conversion F8."

API Annotations de graphique

Annotations créées par le client (déploiements, versions, campagnes, incidents, custom) qui se superposent à chaque graphique temporel du tableau de bord Zenovay. Également utilisées par le triage des incidents de conversion comme "changements suspects" dans une fenêtre de ±2 h autour du début d'un incident.

Auth : ce point d'API accepte votre cookie de session du tableau de bord. Pour les intégrations CI, utilisez la CLI Zenovay qui gère l'authentification via votre connexion de compte. Les clés API externes zv_* ne sont pas acceptées sur ce point aujourd'hui ; la CLI est la voie canonique pour créer des annotations depuis un pipeline de déploiement.

Limites de plan : Gratuit = 10 annotations/mois. Pro+ = illimité.

Déduplication : une annotation du même type dans les 5 minutes d'une existante est rejetée avec 409 Conflict. Cela empêche un CI mal configuré d'inonder la timeline.

Créer une annotation

POST /api/annotations
Content-Type: application/json
Cookie: zenovay-session=<your-session-cookie>xxxxxxxxxxxxxxxxxxxxx

{
  "websiteId": "11111111-2222-3333-4444-555555555555",
  "type": "deploy",
  "message": "Déploiement checkout v2.5",
  "occurredAt": "2026-04-30T14:00:00Z",
  "metadata": { "sha": "a1b2c3d", "branch": "main" }
}

Champs

Réponse

{
  "success": true,
  "data": {
    "annotation": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "website_id": "11111111-2222-3333-4444-555555555555",
      "team_id": "...",
      "type": "deploy",
      "message": "Déploiement checkout v2.5",
      "occurred_at": "2026-04-30T14:00:00Z",
      "created_by": "...",
      "metadata_json": { "sha": "a1b2c3d", "branch": "main" },
      "created_at": "2026-04-30T14:00:01Z"
    }
  }
}

Lister les annotations

GET /api/annotations?websiteId=<uuid>&from=<iso>&to=<iso>
Cookie: zenovay-session=<your-session-cookie>

from et to sont optionnels. Renvoie jusqu'à 500 annotations dans la fenêtre, les plus récentes en premier.

Supprimer une annotation

DELETE /api/annotations/<annotation-id>
Cookie: zenovay-session=<your-session-cookie>

Renvoie { deleted: true } en cas de succès. La suppression douce n'est pas supportée en v1 — les suppressions sont permanentes.

Patterns courants

Créer un marqueur de déploiement depuis un pipeline CI

curl -X POST https://api.zenovay.com/api/annotations \
  -H "Authorization: Bearer $ZENOVAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"websiteId\": \"$WEBSITE_ID\",
    \"type\": \"deploy\",
    \"message\": \"Déploiement $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Depuis le CLI Zenovay

zenovay annotation create --type=deploy --message="release v2.5"

Où les annotations apparaissent

• Sur tous les graphiques temporels du tableau de bord (ligne de référence verticale + puce colorée dans la légende flottante).
• Triage des incidents de conversion — les incidents dans une fenêtre de ±2 h d'une annotation l'inscrivent automatiquement comme "changement suspect".
• Tableaux de bord publics — les annotations ne sont pas affichées sur les tableaux de bord publics. Les messages de déploiement et de release sont destinés à l'équipe qui exploite le site, pas aux visiteurs.

Erreurs