Chart-Annotations-API

Von Kunden erstellte Annotations (Deploys, Releases, Kampagnen, Vorfälle, benutzerdefiniert), die auf jeden Zeitreihen-Chart im Zenovay-Dashboard überlagert werden. Sie werden auch vom Conversion-Incident-Triage als „verdächtige Änderungen" innerhalb von ±2 h um den Vorfallsbeginn herangezogen.

Auth: Dieser Endpunkt akzeptiert Ihr Dashboard-Session-Cookie. Für CI-Integrationen und Automatisierung verwenden Sie die Zenovay-CLI, die die Authentifizierung über Ihr Konto-Login handhabt. Externe zv_*-API-Keys werden auf diesem Endpunkt derzeit nicht akzeptiert; die CLI ist der kanonische Weg, um Annotations aus einer Deploy-Pipeline zu erstellen.

Plan-Limits: Free = 10 Annotations / Monat. Pro+ = unbegrenzt.

Dedup: Eine gleichartige Annotation innerhalb von 5 Minuten einer vorhandenen wird mit 409 Conflict abgelehnt. Dies verhindert, dass fehlkonfigurierte CI die Timeline mit Spam überschwemmt.

Annotation erstellen

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" }
}

Felder

Antwort

{
  "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"
    }
  }
}

Annotations auflisten

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

from und to sind optional. Liefert bis zu 500 Annotations innerhalb des Fensters, neueste zuerst.

Annotation löschen

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

Liefert { deleted: true } bei Erfolg. Soft-Delete wird in v1 nicht unterstützt — Löschen ist permanent.

Häufige Muster

Deploy-Marker aus einer CI-Pipeline erstellen

Verwenden Sie die Zenovay-CLI für CI-Pipelines — der curl-Ansatz mit Session-Cookie ist in automatisierten Umgebungen unpraktisch. Siehe das CLI-Beispiel unten.

Falls Sie einen Raw-HTTP-Aufruf benötigen (z. B. von einem Server, der bereits ein gültiges Session-Cookie hat), sieht der Request so aus:

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\" }
  }"

Aus der Zenovay-CLI

Die Zenovay-CLI ist der empfohlene Weg, um Annotations aus einer CI-Pipeline zu erstellen — sie handhabt die Authentifizierung automatisch über den OAuth-Device-Flow-Login.

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

Der vollständige Satz von Flags:

Siehe die CLI-Integrations-Seite für die vollständige Befehlsreferenz und ein Beispiel-GitHub-Actions-Step.

Wo Annotations angezeigt werden

• Auf jedem Zeitreihen-Chart im Dashboard (vertikale Referenzlinie
  • farbiger Chip in der schwebenden Legende).
• Conversion-Incident-Triage — Vorfälle innerhalb von ±2 h einer Annotation listen sie automatisch als „verdächtige Änderung" auf.
• Öffentliche Dashboards — Annotations werden auf öffentlichen Dashboards nicht angezeigt. Deploy- und Release-Nachrichten sind für das Team gedacht, das die Website betreibt, nicht für Besucher.

Fehler