API para desarrolladores de Wave
Crea un token con permisos específicos y lee, actualiza o importa sesiones, transcripciones y tareas de Wave desde tu propio código, con búsqueda, exportación masiva y webhooks.
Última actualización:
La API para desarrolladores de Wave AI es una API REST sobre tus propias grabaciones. Apunta tu código a https://api.wave.co/v1 con un token que crees en Wave, y podrás listar sesiones, leer resúmenes y transcripciones, buscar por significado, descargar audio, importar grabaciones, actualizar títulos, resúmenes y tareas, y recibir un webhook en el momento en que una grabación termine de procesarse.
Es gratis en todos los planes de Wave, y solo accede a tu propia cuenta.
Crear un token
En la aplicación web de Wave en app.wave.co, ve a Settings → Developers ("Configuración → Desarrolladores") y abre API tokens and webhooks — o ve directamente a app.wave.co/settings/integrations/api.
En API tokens, haz clic en Create token.
Dale un Token name ("Nombre del token") que reconozcas después, marca los Permissions ("Permisos") que necesite y haz clic en Create token. Es mucho más fácil gestionar un token por integración que uno compartido.
Copia el token desde el diálogo Token created. Wave lo muestra una sola vez: Copy this token now. You will not be able to see it again. ("Copia este token ahora. No podrás volver a verlo").
Envíalo como bearer token en cada solicitud:
curl -H "Authorization: Bearer wave_api_xxx..." \
https://api.wave.co/v1/sessionsLa lista de tokens muestra el nombre de cada uno, su prefijo wave_api_, sus permisos, y cuándo se creó, se usó por última vez y cuándo expira. El icono de la papelera pregunta Revoke this token? ("¿Revocar este token?") — selecciona Revoke token y el efecto es inmediato; cualquier cosa que use ese token empieza a recibir un 401.
Los tokens de API expiran un año después de crearse. Si una integración que funcionó bien durante meses de repente devuelve 401 invalid_token, revisa la fecha Expires en la lista de tokens y crea uno nuevo.
Permisos
Los permisos son por token. Otorga los mínimos necesarios para la tarea.
| Permiso | Qué permite |
|---|---|
| Read sessions | Listar y abrir sesiones, estadísticas, personas, exportación masiva |
| Write sessions and action items | Actualizar título, notas, resumen, etiquetas, favorito, tareas |
| Delete sessions | Eliminar una sesión de forma permanente |
| Search sessions | Búsqueda semántica en toda tu biblioteca |
| Read transcripts | Transcripciones completas con segmentos por interlocutor |
| Access media | URLs de descarga firmadas para audio y video |
| Read account | Información de la cuenta y estado de la suscripción |
| Manage webhooks | Registrar y gestionar endpoints de webhooks |
| Read event feed | Obtener y confirmar el feed de eventos |
| Read folders | Listar y abrir carpetas (Read sessions también funciona) |
| Manage folders | Crear, renombrar, recolorear, fijar, reordenar y eliminar carpetas, y añadir o quitar sesiones |
| Share sessions and manage access | Compartir tus sesiones con otros usuarios de Wave, ver quién tiene acceso y eliminar personas |
| Import recordings (uses your import allowance) | Importar audio y video a Wave por enlace o subida. Nunca incluido en el permiso de escritura; actívalo por separado |
Si llamas a un endpoint sin el permiso correspondiente, obtienes un 403 que indica qué falta.
Lectura de tus datos
GET /v1/sessions— las más recientes primero, paginadas por cursor, filtrables portype,since,folder,tagyperson. Solo se devuelven las sesiones que terminaron de procesarse.folderacepta un id, un nombre o una rutaParent/Child; una carpeta principal incluye las sesiones de sus subcarpetas, salvo que pasesinclude_subfolders=false.GET /v1/sessions/:id— título, duración, resumen en markdown, notas, etiquetas, favorito. Las llamadas telefónicas también incluyen dirección y números.GET /v1/sessions/:id/transcript— una cadena de transcripción plana más segmentos con tiempo y etiquetados por interlocutor.GET /v1/sessions/:id/action-items— tareas estructuradas y un número de versión.GET /v1/sessions/:id/media— URLs de audio y video firmadas, válidas por una hora.POST /v1/sessions/search— búsqueda semántica, hasta 50 resultados, filtros opcionales por etiqueta.POST /v1/sessions/bulk— hasta 50 sesiones en una sola llamada, con resúmenes y transcripciones. La forma rápida de recuperar datos históricos.GET /v1/folders,GET /v1/folders/:id,GET /v1/sessions/stats— carpetas, y totales por tipo y plataforma. Las carpetas se anidan un solo nivel: cada carpeta tiene unparent_id(nullen el nivel superior), yGET /v1/folders?parent_id=noneo?parent_id={id}lista un nivel.
Personas
Las personas son las voces que guardaste como Voice ID. Solo necesitan el permiso Read Sessions, y son de solo lectura.
GET /v1/people— todas las personas para las que guardaste una voz, con cuántas grabaciones tiene cada una y cuándo se escuchó por última vez. Tu propia voz está marcada comois_mey aparece primero.GET /v1/people/:id/sessions— las grabaciones de una persona, las más recientes primero, paginadas por cursor, filtrables portype,fromyto. Cada fila muestra cuánto habló, el nombre que tiene en esa transcripción y sus tres líneas más largas. Usamecomo id para tu propia voz.GET /v1/sessions?person=:id— la lista normal de sesiones, limitada a las grabaciones en las que aparece esa persona.
Nunca se devuelven muestras de voz, ni tampoco transcripciones completas; obtén una transcripción por separado cuando necesites más que las tres líneas. Si fusionaste dos Voice ID en Wave, el id antiguo devuelve un 404 cuyo merged_into indica el id que debes usar. Mientras Wave todavía está indexando las personas de una cuenta, los conteos solo cubren las 1000 grabaciones más recientes y las respuestas incluyen partial: true.
Escritura de datos
PATCH /v1/sessions/:id establece título, notas, resumen (markdown), etiquetas, favorito y tareas. Para las tareas, léelas primero y envía de vuelta la versión que obtuviste — así una edición simultánea en la aplicación Wave se rechaza en lugar de sobrescribirse silenciosamente. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id, y los endpoints de pertenencia a carpetas (POST y DELETE /v1/sessions/:id/folders/:folderId) organizan las sesiones. Las carpetas no son exclusivas, así que una sesión puede estar en varias, y eliminar una carpeta no elimina las sesiones que contiene. Pasa parent_id a POST /v1/folders para crear una subcarpeta, o a PATCH /v1/folders/:id para mover una carpeta (null la devuelve al nivel superior). La carpeta principal debe ser de nivel superior, y una carpeta con subcarpetas no se puede mover dentro de otra; en ambos casos se devuelve un 400 invalid_parent. Al eliminar una carpeta principal, sus subcarpetas pasan al nivel superior.
DELETE /v1/sessions/:id es permanente y no es lo mismo que eliminar desde la aplicación. Trátalo como irrecuperable.
Importación de grabaciones
POST /v1/sessions/import crea una sesión a partir de un archivo de audio o video. Wave lo transcribe y resume exactamente igual que un archivo importado desde la aplicación. Necesita el permiso Import recordings (uses your import allowance) (sessions:import). Envía uno de estos:
source_url: un enlace https público al archivo en sí. Wave lo descarga (hasta 2 GiB) y responde202constatus: "fetching".upload: con uncontent_type(y opcionalmentefilenameysize_bytes). Wave responde201con unaupload.urlfirmada. Haz un PUT del archivo ahí dentro de 15 minutos con exactamente losupload.headersque te da (hasta 5 GiB). El procesamiento empieza automáticamente cuando termina la subida.
También puedes pasar title, notes, tags, language y recorded_at. Luego consulta GET /v1/sessions/:id para ver processing_status, o espera el webhook Session completed.
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"}'Envía un encabezado Idempotency-Key para que los reintentos sean seguros: repetir la misma clave y el mismo cuerpo devuelve la sesión original en lugar de crear una segunda importación.
Formatos admitidos: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG y MPEG-TS. Las importaciones comparten el límite de importación de tu cuenta con las aplicaciones de Wave: 12 por hora y 20 por día (40 y 100 para clientes de pago; menos para cuentas con menos de dos días de antigüedad). Por encima de eso recibes un 429 import_rate_limited, y un plan gratuito sin minutos restantes recibe un 403 subscription_required.
Compartir
Un token actúa como tú, así que puede leer las sesiones que otros usuarios de Wave compartieron contigo con los permisos descritos arriba. GET /v1/shared-sessions las lista, y GET /v1/shared-sessions/{owner_id}/{id} junto con sus rutas /transcript, /action-items y /media leen una de ellas. Añade include=shared a GET /v1/sessions para mezclarlas con tu propia lista; cada fila entonces incluye access (owner o shared) y, en las filas compartidas, el propietario. Las filas compartidas no se pueden filtrar por carpeta o etiqueta, las sesiones compartidas son de solo lectura, y la búsqueda solo cubre tus propias sesiones.
Con Share sessions and manage access, un token puede compartir tus propias sesiones: /v1/sessions/{id}/sharing muestra quién tiene acceso, y las rutas bajo ella crean un enlace de invitación, envían invitaciones por correo (hasta 10 direcciones por llamada), cancelan una invitación pendiente, eliminan a una persona o reinician el enlace. Consulta Compartir sesiones desde Claude, ChatGPT, la API y la CLI para ver la lista completa y los límites.
Límites de uso
Cada token tiene 60 solicitudes por minuto y 10 000 solicitudes por día. Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, y un 429 incluye Retry-After — espera antes de reintentar en lugar de hacerlo de inmediato.
Repetir la misma búsqueda más de diez veces en una hora también devuelve un 429. Las búsquedas idénticas devuelven resultados idénticos, así que usa webhooks o GET /v1/sessions?since= para encontrar lo nuevo.
Webhooks
En lugar de hacer sondeos, haz que Wave te envíe un POST. En la sección Webhooks, haz clic en Add webhook, introduce una Endpoint URL (solo HTTPS, y las URLs que resuelvan a direcciones privadas se rechazan), elige tus Events y haz clic en Create webhook. El Signing secret se muestra una sola vez — guárdalo en ese momento. Puedes tener hasta cinco webhooks.
Los eventos: Session completed (se envía una vez, después de que el procesamiento termina y el resumen puede consultarse; el que la mayoría de las integraciones necesita), Session updated, Action items updated (se envía cuando las tareas se escriben o editan a través de la API) y Session deleted. También puedes registrar un webhook desde tu propio código con POST /v1/webhooks (o wave webhooks create).
Session completed puede llevar más que el resumen. Al crear un webhook con POST /v1/webhooks, o modificar uno con PATCH /v1/webhooks/:id, pasa un objeto include:
{ "include": { "summary": true, "transcript": true, "action_items": true } }summary está activado por defecto; transcript y action_items están desactivados. Incluir la transcripción requiere un token con Read transcripts. Las transcripciones muy largas se cortan a 200 000 caracteres y se marcan con transcript_truncated: true; obtén el resto desde GET /v1/sessions/:id/transcript. Las tareas son las que existen en la sesión cuando se completa; si Wave añade más poco después, recibes un evento Action items updated. Los demás eventos siempre incluyen la sesión simple.
Cada entrega está firmada con tu secreto y llega con los encabezados X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp y X-Wave-Webhook-Signature. Verifica la firma antes de confiar en un payload; la cadena exacta a firmar está en la referencia de la API.
Wave no garantiza una sola entrega por evento. Una entrega que exceda el tiempo de espera (10 segundos) o devuelva un código distinto de 2xx se reintenta hasta tres veces con una espera corta y creciente — unos 10 segundos, luego un minuto, luego cinco minutos — y el mismo evento puede llegar legítimamente más de una vez. Haz que tu manejador sea idempotente: usa X-Wave-Webhook-Id como clave, ignora un id que ya procesaste y devuelve un 2xx rápidamente. Un endpoint que esté caído más tiempo que esa ventana pierde los eventos que no recibió, así que usa el feed de eventos descrito abajo para ponerte al día.
Si un endpoint falla diez veces seguidas, Wave lo marca como Turned off automatically ("Desactivado automáticamente") y deja de enviarle datos. Corrige el endpoint y luego selecciona Turn webhook back on ("Reactivar webhook") en la fila del webhook.
¿Sin servidor? Usa el feed de eventos
Si no puedes alojar una URL pública, haz sondeos en su lugar. GET /v1/events devuelve los eventos posteriores a un cursor que Wave rastrea por token, y POST /v1/events/ack lo avanza una vez que los procesaste, así reiniciar un script no repite todo. Las páginas tienen 50 elementos por defecto y un máximo de 200, y el feed también incluye cambios en tareas. Requiere el permiso Read event feed.
La CLI de Wave envuelve esto en wave events tail por si prefieres no escribir tú mismo el bucle de sondeo.
Preguntas frecuentes
api.wave.co/reference tiene todos los endpoints, parámetros y formatos de respuesta con ejemplos en vivo. api.wave.co/llms.txt es el mismo contenido en texto plano — pégalo en un asistente de IA y haz que escriba la integración por ti.
Siempre en JSON, con un code y un message. Los más comunes: 401 invalid_token (expirado, revocado o mal escrito), 403 insufficient_scope (al token le falta un permiso) y 429 (límite de uso alcanzado).
Solo las que esas personas compartieron contigo. Un token está vinculado a la cuenta que lo creó: devuelve las sesiones de esa cuenta, más las sesiones que otros usuarios de Wave compartieron con esa cuenta, de solo lectura.
¿Te resultó útil este artículo?
¿Necesitas más ayuda?
El kit de herramientas Wave Agents: conecta tus datos con cualquier otra herramienta
Tres formas de llevar tus grabaciones de Wave a otras herramientas: MCP para asistentes de IA, una API REST para tu propio código y una CLI para la terminal.
Compartir sesiones desde Claude, ChatGPT, la API y la CLI
Lee las sesiones que otras personas comparten contigo y comparte las tuyas, desde un asistente de IA, tu propio código o la terminal.