---

title: "Chart-Annotations-API" description: "Erstellen Sie Deploy-/Release-/Kampagnen-Annotations, die auf jedem Zenovay-Zeitreihen-Chart erscheinen und das F8-Conversion-Incident-Triage speisen."

Chart-Annotations-API

Vom Kunden erstellte Annotations (Deploys, Releases, Kampagnen, Vorfälle, custom), die auf jedem Zeitreihen-Chart im Zenovay-Dashboard überlagert werden. 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 das Zenovay CLI, das die Authentifizierung über Ihr Konto-Login abwickelt. Externe zv_*-API-Keys werden auf diesem Endpunkt heute nicht akzeptiert; das CLI ist der empfohlene Weg, Annotations aus einer Deploy-Pipeline zu erstellen.

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

Dedup: Eine gleichartige Annotation innerhalb von 5 Minuten zu einer bestehenden wird mit 409 Conflict abgelehnt — das verhindert Spam von fehlkonfigurierten CI-Pipelines.

Annotation erstellen

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

{
  "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 im Fenster, neueste zuerst.

Annotation löschen

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

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

Häufige Muster

Deploy-Marker aus einer CI-Pipeline erstellen

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\": \"Deploy $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Aus der Zenovay-CLI

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

Wo Annotations erscheinen

• 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 Site betreibt, nicht für Besucher.

Fehler