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/sessionsA 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ão | O que permite |
|---|---|
| Read sessions | Listar e abrir sessões, estatísticas, pessoas, exportação em massa |
| Write sessions and action items | Atualizar título, notas, resumo, tags, favorito, itens de ação |
| Delete sessions | Excluir uma sessão permanentemente |
| Search sessions | Busca semântica em toda a sua biblioteca |
| Read transcripts | Transcrições completas com segmentos por interlocutor |
| Access media | URLs de download assinadas para áudio e vídeo |
| Read account | Informações da conta e status da assinatura |
| Manage webhooks | Registrar e gerenciar endpoints de webhook |
| Read event feed | Buscar e confirmar o feed de eventos |
| Read folders | Listar e abrir pastas (Read sessions também funciona) |
| Manage folders | Criar, renomear, recolorir, fixar, reordenar e excluir pastas, além de adicionar ou remover sessões |
| Share sessions and manage access | Compartilhar 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 portype,since,folder,tageperson. Só retorna sessões que terminaram de ser processadas.folderaceita um id, um nome ou um caminhoParent/Child; uma pasta principal inclui as sessões das suas subpastas, a menos que você passeinclude_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 umparent_id(nullno nível superior), eGET /v1/folders?parent_id=noneou?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 comois_mee aparece primeiro.GET /v1/people/:id/sessions— as gravações de uma pessoa, mais recentes primeiro, paginação por cursor, filtrável portype,frometo. Cada linha mostra quanto tempo a pessoa falou, o nome que ela tem nessa transcrição e suas três falas mais longas. Usemecomo 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 responde202comstatus: "fetching".upload: com umcontent_type(e, opcionalmente,filenameesize_bytes). O Wave responde201com umaupload.urlassinada. Faça um PUT do arquivo nessa URL em até 15 minutos, usando exatamente osupload.headersfornecidos (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
api.wave.co/reference tem todos os endpoints, parâmetros e formatos de resposta, com exemplos ao vivo. api.wave.co/llms.txt traz o mesmo material em texto simples — cole em um assistente de IA e peça para ele escrever a integração para você.
Sempre em JSON, com um code e uma message. Os mais comuns: 401 invalid_token (expirado, revogado ou digitado errado), 403 insufficient_scope (o token não tem uma permissão) e 429 (limite de requisições atingido).
Somente as que outras pessoas compartilharam com você. Um token está vinculado à conta que o criou: ele retorna as sessões dessa conta, além das sessões que outros usuários do Wave compartilharam com essa conta, de forma somente leitura.
Este artigo foi útil?
Ainda precisa de ajuda?
O Wave Agents Toolkit: conecte os teus dados a qualquer outra ferramenta
Três formas de levar as tuas gravações do Wave para outras ferramentas: MCP para assistentes de IA, uma REST API para o teu próprio código, e uma CLI para o terminal.
Compartilhar sessões a partir do Claude, ChatGPT, API e CLI
Leia as sessões que outras pessoas compartilharam com você e compartilhe as suas, a partir de um assistente de IA, do seu próprio código ou do terminal.