Help Center

API para desenvolvedores do Wave

Crie um token com permissões específicas e leia, atualize ou importe sessões, transcrições e itens de ação do Wave a partir do seu próprio código, com busca, exportação em massa e webhooks.

Última atualização:

A API para desenvolvedores do Wave AI é 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, importar gravações, atualizar títulos, resumos e itens de ação, além de receber um webhook assim que uma gravação terminar de ser processada.

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

Criar um token

No app web do Wave em app.wave.co, vá em Settings → Developers ("Configurações → Desenvolvedores") e abra API tokens and webhooks — ou acesse diretamente app.wave.co/settings/integrations/api.

Em API tokens, clique em Create token ("Criar token").

Dê um Token name ("Nome do token") que você vai reconhecer depois, marque as Permissions ("Permissões") necessárias e clique em Create token. Um token por integração é muito mais fácil de gerenciar do que um token compartilhado entre várias.

Copie o token na caixa de diálogo Token created ("Token criado"). O Wave mostra ele uma única vez: Copy this token now. You will not be able to see it again. ("Copie este token agora. Você não poderá vê-lo novamente.")

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_, suas permissões e quando foi criado, usado pela última vez e quando expira. O ícone de lixeira pergunta Revoke this token? ("Revogar este token?") — selecione Revoke token ("Revogar token") e a revogação passa a valer imediatamente; qualquer coisa que use esse token passa a receber um 401.

Os tokens de API expiram um ano após serem criados. Se uma integração que funcionava bem há meses de repente começar a retornar 401 invalid_token, verifique a data em Expires ("Expira em") na lista de tokens e crie um token novo.

Permissões

As permissões são por token. Conceda apenas as mínimas necessárias para a tarefa.

PermissãoO que permite
Read sessionsListar e abrir sessões, estatísticas, pessoas, exportação em massa
Write sessions and action itemsAtualizar título, notas, resumo, tags, favorito, itens de ação
Delete sessionsExcluir uma sessão permanentemente
Search sessionsBusca semântica em toda a sua biblioteca
Read transcriptsTranscrições completas com segmentos por interlocutor
Access mediaURLs de download assinadas para áudio e vídeo
Read accountInformações da conta e status da assinatura
Manage webhooksRegistrar e gerenciar endpoints de webhook
Read event feedBuscar e confirmar o feed de eventos
Read foldersListar e abrir pastas (Read sessions também funciona)
Manage foldersCriar, renomear, recolorir, fixar, reordenar e excluir pastas, além de adicionar ou remover sessões
Share sessions and manage accessCompartilhar suas sessões com outros usuários do Wave, ver quem tem acesso e remover pessoas
Import recordings (uses your import allowance)Importar áudio e vídeo para o Wave por link ou upload. Nunca incluída na permissão de escrita; marque-a separadamente

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

Lendo seus dados

  • GET /v1/sessions — mais recentes primeiro, paginação por cursor, filtrável por type, since, folder, tag e person. Só retorna sessões que terminaram de ser processadas. folder aceita um id, um nome ou um caminho Parent/Child; uma pasta principal inclui as sessões das suas subpastas, a menos que você passe include_subfolders=false.
  • 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 cronometrados e identificados por 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 opcionais por tag.
  • 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/folders/:id, GET /v1/sessions/stats — pastas e totais por tipo e plataforma. As pastas aninham-se em um só nível: cada pasta tem um parent_id (null no nível superior), e GET /v1/folders?parent_id=none ou ?parent_id={id} lista um nível.

Pessoas

Pessoas são as vozes que você salvou como Voice IDs. Elas precisam apenas da permissão Read Sessions, e são somente leitura.

  • GET /v1/people — todos para quem você salvou uma voz, com quantas gravações cada um aparece e quando foi ouvido pela última vez. Sua própria voz é marcada como is_me e aparece primeiro.
  • GET /v1/people/:id/sessions — as gravações de uma pessoa, mais recentes primeiro, paginação por cursor, filtrável por type, from e to. Cada linha mostra quanto tempo a pessoa falou, o nome que ela tem nessa transcrição e suas três falas mais longas. Use me como id para sua própria voz.
  • GET /v1/sessions?person=:id — a lista comum de sessões, restrita às gravações em que essa pessoa aparece.

Amostras de voz nunca são retornadas, assim como transcrições completas; busque a transcrição separadamente quando precisar de mais do que as três falas. Se você mesclou dois Voice IDs no Wave, o id antigo retorna um 404 cujo merged_into indica o id a usar. Enquanto o Wave ainda estiver indexando as pessoas de uma conta, as contagens cobrem apenas as 1.000 gravações mais recentes e as respostas trazem partial: true.

Escrevendo de volta

PATCH /v1/sessions/:id define título, notas, resumo (markdown), 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 — assim, uma edição simultânea no app Wave é rejeitada em vez de sobrescrita silenciosamente. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id e os endpoints de associação a pastas (POST e DELETE /v1/sessions/:id/folders/:folderId) organizam as sessões. As pastas não são exclusivas, então uma sessão pode estar em várias, e excluir uma pasta não exclui as sessões dentro dela. Passe parent_id para POST /v1/folders para criar uma subpasta, ou para PATCH /v1/folders/:id para mover uma pasta (null devolve-a ao nível superior). A pasta principal tem de ser de nível superior, e uma pasta com subpastas não pode ser movida para dentro de outra; os dois casos retornam um 400 invalid_parent. Apagar uma pasta principal passa as suas subpastas para o nível superior.

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

Importando gravações

POST /v1/sessions/import cria uma sessão a partir de um arquivo de áudio ou vídeo. O Wave transcreve e resume exatamente como faria com um arquivo importado pelo app. Precisa da permissão Import recordings (uses your import allowance) (sessions:import). Envie um dos seguintes:

  • source_url: um link https público para o próprio arquivo. O Wave baixa o arquivo (até 2 GiB) e responde 202 com status: "fetching".
  • upload: com um content_type (e, opcionalmente, filename e size_bytes). O Wave responde 201 com uma upload.url assinada. Faça um PUT do arquivo nessa URL em até 15 minutos, usando exatamente os upload.headers fornecidos (até 5 GiB). O processamento começa automaticamente assim que o upload termina.

Você também pode passar title, notes, tags, language e recorded_at. Depois, consulte GET /v1/sessions/:id repetidamente para acompanhar processing_status, ou escute o webhook Session completed ("Sessão concluída").

curl -X POST https://api.wave.co/v1/sessions/import \
  -H "Authorization: Bearer wave_api_xxx..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: standup-2026-10-21" \
  -d '{"source_url": "https://example.com/standup.mp3", "title": "Daily standup"}'

Envie um cabeçalho Idempotency-Key para tornar as tentativas repetidas seguras: repetir a mesma chave e o mesmo corpo retorna a sessão original em vez de criar uma segunda importação.

Formatos suportados: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG e MPEG-TS. As importações compartilham o limite de importação da sua conta com os apps do Wave: 12 por hora e 20 por dia (40 e 100 para clientes pagantes; menos para contas com menos de dois dias de existência). Acima disso, você recebe um 429 import_rate_limited, e um plano gratuito sem minutos restantes recebe um 403 subscription_required.

Compartilhamento

Um token age em seu nome, então pode ler as sessões que outros usuários do Wave compartilharam com você, de acordo com as permissões acima. GET /v1/shared-sessions as lista, e GET /v1/shared-sessions/{owner_id}/{id}, junto com /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 passa então a trazer access (owner ou shared) e, nas linhas compartilhadas, o proprietário. As 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 and 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, enviam convites por e-mail (até 10 endereços por chamada), cancelam um convite pendente, removem uma pessoa ou reiniciam o link. Veja Sharing Sessions from Claude, ChatGPT, the API and the 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 429 inclui Retry-After — espere antes de tentar novamente, em vez de repetir imediatamente.

Repetir a mesma 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 encontrar o que é novo.

Webhooks

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

Os eventos: Session completed (enviado uma vez, depois que o processamento termina e o resumo já pode ser consultado; o que a maioria das integrações quer), Session updated ("Sessão atualizada"), Action items updated ("Itens de ação atualizados"; enviado quando itens de ação são criados ou editados pela API) e Session deleted ("Sessão excluída"). Você também pode registrar um webhook pelo seu próprio código com POST /v1/webhooks (ou wave webhooks create).

Session completed pode trazer mais do que o resumo. Ao criar um webhook com POST /v1/webhooks, ou ao alterar um com PATCH /v1/webhooks/:id, envie um objeto include:

{ "include": { "summary": true, "transcript": true, "action_items": true } }

summary vem ativado por padrão; transcript e action_items vêm desativados. Incluir a transcrição requer um token com Read transcripts. Transcrições muito longas são cortadas em 200.000 caracteres e marcadas com transcript_truncated: true; busque o restante em GET /v1/sessions/:id/transcript. Os itens de ação são os que a sessão tinha no momento da conclusão; se o Wave adicionar mais pouco depois, você recebe um evento Action items updated. Os demais eventos sempre trazem a sessão simples.

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 ser assinada está na referência da API.

O Wave não garante uma única entrega por evento. Uma entrega que expira (10 segundos) ou retorna um status não-2xx é repetida até três vezes, com um pequeno intervalo crescente — cerca de 10 segundos, depois um minuto, depois cinco minutos — e o mesmo evento pode legitimamente chegar mais de uma vez. Torne seu handler idempotente: use X-Wave-Webhook-Id como chave, ignore um id que você já processou e retorne um 2xx rapidamente. Um endpoint que fica fora do ar por mais tempo do que essa janela perde os eventos que não recebeu, então use o feed de eventos abaixo para se atualizar.

Se um endpoint falhar dez vezes seguidas, o Wave o marca como Turned off automatically ("Desativado automaticamente") e para de enviar. Corrija o endpoint e depois selecione Turn webhook back on ("Reativar webhook") na linha do webhook.

Sem servidor? Use o feed de eventos

Se você não puder hospedar uma URL pública, faça polling em vez disso. GET /v1/events retorna os eventos a partir de um cursor que o Wave mantém por token, e POST /v1/events/ack avança esse cursor depois 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. Requer a permissão Read event feed.

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

Perguntas frequentes

Este artigo foi útil?

Ainda precisa de ajuda?

E-mail para o suporte

Nesta página