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 ±2h 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 canonical 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>

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

Resposta

{
  "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 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 dentro da janela, mais recentes primeiro.

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 marcador de deploy a partir de um pipeline CI

Use a CLI da Zenovay para pipelines de CI — a abordagem de cookie de sessão com curl é impraticável em ambientes automatizados. Veja o exemplo de CLI abaixo.

Se você precisar de uma chamada HTTP bruta (por exemplo, de um servidor que já possui um cookie de sessão válido), a solicitação fica assim:

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

Pela CLI da Zenovay

A CLI da Zenovay é a forma recomendada para criar anotações a partir de um pipeline de CI — ela cuida da autenticação automaticamente via login OAuth de fluxo de dispositivo.

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

O conjunto completo de sinalizadores:

Veja a página de integração de CLI para a referência completa de comandos e um exemplo de etapa do GitHub Actions.

Onde as anotações aparecem

• Cada gráfico de série temporal no painel (linha vertical de referência + chip colorido na legenda flutuante).
• Triagem de incidentes de conversão — incidentes dentro de ±2h 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