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>

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

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

Usa la CLI de Zenovay para pipelines CI — el enfoque de cookie de sesión con curl no es práctico en entornos automatizados. Consulta el ejemplo de CLI a continuación.

Si necesitas una llamada HTTP pura (p. ej., desde un servidor que ya tiene una cookie de sesión válida), la solicitud se vería así:

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

Desde la CLI de Zenovay

La CLI de Zenovay es la forma recomendada de crear anotaciones desde un pipeline CI — gestiona la autenticación automáticamente a través del inicio de sesión del flujo de dispositivo OAuth.

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

El conjunto completo de banderas:

Consulta la página de integración de CLI para la referencia de comando completa y un paso de GitHub Actions de ejemplo.

Dónde aparecen las anotaciones

• Cada gráfico 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 un "cambio sospechoso".
• Paneles públicos — las anotaciones no se muestran en paneles públicos. Los mensajes de despliegue y lanzamiento están dirigidos al equipo que opera el sitio, no a los visitantes.

Errores