API para desenvolvedores da Wave

A API para desenvolvedores da Wave é uma REST API sobre as suas próprias gravações. Aponte seu código para https://api.wave.co/v1 com um token que você cria na Wave, e você pode listar sessões, ler resumos e transcrições, buscar por significado, baixar áudio, atualizar títulos e itens de ação, e receber um webhook no momento em que uma gravação termina de ser processada.

É gratuita em todos os planos da Wave, e só acessa a sua própria conta.

Crie um token

Envie-o como um bearer token em cada requisição:

curl -H "Authorization: Bearer wave_api_xxx..." \
  https://api.wave.co/v1/sessions

A lista de tokens mostra o nome de cada um, seu prefixo wave_api_, quando foi criado e quando foi usado pela última vez. O ícone de lixeira abre Revoke Token ("Revogar token") — a revogação tem efeito imediato, e qualquer coisa usando aquele token passa a receber um 401.

Permissões

As permissões são por token. Conceda o mínimo necessário para o trabalho.

Ao chamar um endpoint sem a permissão correspondente, você recebe um 403 indicando o que está faltando.

Lendo seus dados

• GET /v1/sessions — mais recentes primeiro, paginado por cursor, filtrável por type, since, folder e tag. Só retorna sessões que terminaram de processar.
• GET /v1/sessions/:id — título, duração, resumo em markdown, notas, tags, favorito. Chamadas telefônicas também trazem direção e números.
• GET /v1/sessions/:id/transcript — uma string de transcrição corrida, além de segmentos com marcação de tempo e interlocutor.
• GET /v1/sessions/:id/action-items — itens de ação estruturados e um número de versão.
• GET /v1/sessions/:id/media — URLs assinadas de áudio e vídeo, válidas por uma hora.
• POST /v1/sessions/search — busca semântica, até 50 resultados, com filtros de tag opcionais.
• POST /v1/sessions/bulk — até 50 sessões em uma única chamada, com resumos e transcrições. O jeito mais rápido de preencher retroativamente.
• GET /v1/folders, GET /v1/sessions/stats — pastas e totais por tipo e plataforma.

Escrevendo de volta

PATCH /v1/sessions/:id define título, notas, tags, favorito e itens de ação. Para itens de ação, leia-os primeiro e envie de volta a versão recebida — assim, uma edição simultânea no app da Wave é rejeitada em vez de ser sobrescrita silenciosamente. POST /v1/folders e os endpoints de participação em pastas organizam sessões; as pastas não são exclusivas, então uma sessão pode estar em várias.

DELETE /v1/sessions/:id é permanente e não é a mesma coisa que excluir pelo app. Trate como irreversível.

Limites de requisição

Cada token tem direito a 60 requisições por minuto e 10.000 requisições por dia. As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, e um 429 inclui Retry-After — espere em vez de tentar novamente na hora.

Repetir a mesma consulta de busca mais de dez vezes por hora também retorna um 429. Buscas idênticas retornam resultados idênticos, então use webhooks ou GET /v1/sessions?since= para descobrir o que há de novo.

Webhooks

Em vez de fazer polling, deixe a Wave enviar um POST para você. Na seção Webhooks, clique em Add Webhook ("Adicionar webhook"), informe uma Endpoint URL ("URL do endpoint") (somente HTTPS, e URLs que resolvem para endereços privados são rejeitadas), escolha seus eventos e clique em Create Webhook. O Signing Secret ("Segredo de assinatura") é mostrado uma única vez — guarde-o nesse momento. Você pode ter até cinco webhooks.

Três eventos estão disponíveis hoje: Session Completed ("Sessão concluída") (disparado uma vez, depois que o processamento termina e o resumo pode ser consultado — o que a maioria das integrações quer), Session Updated ("Sessão atualizada") e Session Deleted ("Sessão excluída").

Cada entrega é assinada com seu segredo e chega com os cabeçalhos X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp e X-Wave-Webhook-Signature. Verifique a assinatura antes de confiar em um payload; a string exata a assinar está na referência da API.

Se um endpoint falhar dez vezes seguidas, a Wave o marca como Auto-disabled ("Desativado automaticamente") e para de enviar. Corrija o endpoint e depois use o botão de reativar na linha do webhook.

Sem servidor? Use o feed de eventos

Se você não pode hospedar uma URL pública, faça polling. GET /v1/events retorna eventos a partir de um cursor que a Wave controla por token, e POST /v1/events/ack avança esse cursor depois que você processa os eventos, então reiniciar um script não reproduz tudo de novo. As páginas trazem 50 itens por padrão, com um limite de 200, e o feed também traz mudanças em itens de ação que as inscrições de webhook não trazem. Requer a permissão Read Event Feed.

O Wave CLI encapsula isso no comando wave events tail, caso você prefira não escrever o loop de polling.

Perguntas frequentes