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 et l'automatisation, 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 chronologie.

Créer une annotation

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

{
  "websiteId": "11111111-2222-3333-4444-555555555555",
  "type": "deploy",
  "message": "Ship 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": "Ship 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

Utilisez la CLI Zenovay pour les pipelines CI — l'approche curl avec cookie de session est impraticale dans les environnements automatisés. Voir l'exemple CLI ci-dessous.

Si vous avez besoin d'un appel HTTP brut (par exemple depuis un serveur qui a déjà un cookie de session valide), la requête ressemble à ceci :

curl -X POST https://api.zenovay.com/api/annotations \
  -H "Cookie: zenovay-session=$ZENOVAY_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d "{
    \"websiteId\": \"$WEBSITE_ID\",
    \"type\": \"deploy\",
    \"message\": \"Deploy $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Depuis la CLI Zenovay

La CLI Zenovay est la façon recommandée de créer des annotations depuis un pipeline CI — elle gère automatiquement l'authentification via la connexion device-flow OAuth.

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

L'ensemble complet des drapeaux :

Voir la page d'intégration CLI pour la référence complète des commandes et un exemple d'étape GitHub Actions.

Où les annotations apparaissent

• 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 version sont destinés à l'équipe qui exploite le site, pas aux visiteurs.

Erreurs