---

title: "API de Anotaciones de Gráficos" description: "Crea anotaciones de despliegue / lanzamiento / campaña que se superponen en cada gráfico de series temporales de Zenovay y alimentan el triaje de incidentes de conversión F8."

API de Anotaciones de Gráficos

Anotaciones creadas por el cliente (despliegues, lanzamientos, campañas, incidentes, personalizadas) que se superponen en cada gráfico de series temporales del panel de Zenovay. También las consume el triaje de incidentes de conversión como "cambios sospechosos" dentro de ±2 h del inicio del incidente.

Auth: este endpoint acepta tu cookie de sesión del panel. Para integraciones de CI y automatización, usa la CLI de Zenovay, que gestiona la autenticación a través del inicio de sesión de tu cuenta. Las claves API externas zv_* no se aceptan en este endpoint hoy; la CLI es la vía recomendada para crear anotaciones desde un pipeline de despliegue.

Límites del plan: Gratis = 10 anotaciones/mes. Pro+ = ilimitado.

Deduplicación: una anotación del mismo type dentro de 5 minutos de una existente se rechaza con 409 Conflict. Esto evita inundar la línea de tiempo con CI mal configurados.

Crear una anotación

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

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

Campos

Respuesta

{
  "success": true,
  "data": {
    "annotation": {
      "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "website_id": "11111111-2222-3333-4444-555555555555",
      "team_id": "...",
      "type": "deploy",
      "message": "Despliegue 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"
    }
  }
}

Listar anotaciones

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

from y to son opcionales. Devuelve hasta 500 anotaciones dentro de la ventana, las más recientes primero.

Eliminar una anotación

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

Devuelve { deleted: true } en caso de éxito. El borrado lógico no está soportado en v1 — los borrados son permanentes.

Patrones comunes

Crear un marcador de despliegue desde 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\": \"Despliegue $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Desde el CLI de Zenovay

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

Dónde aparecen las anotaciones

• En todos los gráficos de series temporales del panel (línea de referencia vertical + chip de color en la leyenda flotante).
• Triaje de incidentes de conversión — los incidentes dentro de ±2 h de una anotación la listan automáticamente como "cambio sospechoso".
• Paneles públicos — las anotaciones no se muestran en paneles públicos. Los mensajes de despliegue y release están dirigidos al equipo que opera el sitio, no a los visitantes.

Errores