API para Desenvolvedores do Wave

A API para Desenvolvedores do Wave é uma API REST sobre suas próprias gravações. Aponte seu código para https://api.wave.co/v1 com um token que você cria no 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.

É gratuito em todos os planos do 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 token, 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 que use aquele token passa a receber um erro 401.

Permissões

As permissões são por token. Conceda apenas as estritamente necessárias.

Chamar um endpoint sem a permissão correspondente retorna um erro 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 ser processadas.
• 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 simples além de segmentos com tempo e interlocutor identificados.
• 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. A forma mais rápida de preencher dados retroativamente.
• GET /v1/folders, GET /v1/sessions/stats — pastas, e totais por tipo e plataforma.

Gravando dados 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 que você recebeu — uma edição simultânea no aplicativo Wave é então rejeitada em vez de sobrescrita silenciosamente. POST /v1/folders e os endpoints de associação a pastas organizam sessões; pastas não são exclusivas, então uma sessão pode estar em várias.

DELETE /v1/sessions/:id é permanente e não é o mesmo que excluir no aplicativo. Trate isso como irreversível.

Compartilhamento

Um token age em seu nome, então ele pode ler as sessões que outros usuários do Wave compartilharam com você com as permissões acima. GET /v1/shared-sessions as lista, e GET /v1/shared-sessions/{owner_id}/{id} junto com seus /transcript, /action-items e /media lê uma delas. Adicione include=shared a GET /v1/sessions para misturá-las com sua própria lista; cada linha então traz access (owner ou shared) e, para linhas compartilhadas, o proprietário. Linhas compartilhadas não podem ser filtradas por pasta ou tag, sessões compartilhadas são somente leitura, e a busca cobre apenas suas próprias sessões.

Com Share Sessions & Manage Access, um token pode compartilhar suas próprias sessões: /v1/sessions/{id}/sharing mostra quem tem acesso, e as rotas abaixo dela criam um link de convite, convites por e-mail (até 10 endereços por chamada), cancelam um convite pendente, removem uma pessoa ou reiniciam o link. Veja Compartilhando Sessões a partir do Claude, ChatGPT, da API e da CLI para a lista completa e os limites.

Limites de requisições

Cada token recebe 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 erro 429 inclui Retry-After — recue em vez de tentar novamente na hora.

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

Webhooks

Em vez de consultar repetidamente, faça o Wave enviar um POST para você. Na seção Webhooks, clique em Add Webhook ("Adicionar Webhook"), insira uma Endpoint URL ("URL do Endpoint") (apenas HTTPS, e URLs que apontam para endereços privados são rejeitadas), escolha seus eventos e clique em Create Webhook. O Signing Secret ("Segredo de Assinatura") é exibido apenas uma vez — guarde-o então. Você pode ter até cinco webhooks.

Três eventos estão disponíveis hoje: Session Completed ("Sessão Concluída") (dispara 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 envio é assinado 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 ser assinada está na referência da API.

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

Sem servidor? Use o feed de eventos

Se você não pode hospedar uma URL pública, consulte em vez disso. GET /v1/events retorna eventos após um cursor que o Wave rastreia por token, e POST /v1/events/ack o avança assim que você os processa, então reiniciar um script não reproduz tudo de novo. As páginas têm 50 itens por padrão e um limite de 200, e o feed também traz mudanças em itens de ação que as assinaturas de webhook não trazem. Requer a permissão Read Event Feed.

O CLI do Wave encapsula isso em wave events tail, caso você prefira não escrever o loop de consulta.

Perguntas frequentes