---

title: "API de Anotações em Gráficos" description: "Crie anotações de deploy / release / campanha que se sobrepõem em cada gráfico de série temporal do Zenovay e alimentam o triagem de incidentes de conversão F8."

API de Anotações em Gráficos

Anotações criadas pelo cliente (deploys, releases, campanhas, incidentes, custom) que se sobrepõem em cada gráfico de série temporal no painel Zenovay. Também são consumidas pelo triagem de incidentes de conversão como "mudanças suspeitas" dentro de ±2 h do início do incidente.

Auth: este endpoint aceita o cookie de sessão do painel. Para integrações de CI e automação, use a CLI da Zenovay, que cuida da autenticação via login da sua conta. Chaves de API externas zv_* não são aceitas neste endpoint hoje; a CLI é o caminho recomendado para criar anotações a partir de um pipeline de deploy.

Limites do plano: Gratuito = 10 anotações/mês. Pro+ = ilimitado.

Dedup: uma anotação do mesmo type dentro de 5 minutos de uma existente é rejeitada com 409 Conflict. Isso evita que CI mal configurado inunde a linha do tempo.

Criar uma anotação

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

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

Campos

Resposta

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

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

from e to são opcionais. Retorna até 500 anotações na janela, das mais recentes para as mais antigas.

Excluir uma anotação

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

Retorna { deleted: true } em caso de sucesso. Soft-delete não é suportado na v1 — exclusões são permanentes.

Padrões comuns

Criar um marker de deploy a partir de um 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\": \"Deploy $GIT_BRANCH @ $GIT_SHA\",
    \"metadata\": { \"sha\": \"$GIT_SHA\", \"branch\": \"$GIT_BRANCH\" }
  }"

Pelo CLI do Zenovay

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

Onde as anotações aparecem

• Em todos os gráficos de série temporal do painel (linha vertical de referência + chip colorido na legenda flutuante).
• Triagem de incidentes de conversão — incidentes dentro de ±2 h de uma anotação a listam automaticamente como "mudança suspeita".
• Painéis públicos — anotações não aparecem em painéis públicos. Mensagens de deploy e release são destinadas à equipe que opera o site, não aos visitantes.

Erros