API para desarrolladores de Wave

La API para desarrolladores de Wave 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, actualizar títulos y tareas pendientes, 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

Envíalo como bearer token en cada solicitud:

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

La lista de tokens muestra el nombre de cada uno, su prefijo wave_api_, cuándo se creó y cuándo se usó por última vez. El ícono de papelera abre Revoke Token ("Revocar token") — la revocación se aplica de inmediato, y cualquier cosa que use ese token empieza a recibir un 401.

Permisos

Los permisos son por token. Otorga los mínimos necesarios para la tarea.

Si llamas a un endpoint sin el permiso correspondiente, obtienes un 403 que indica qué falta.

Leer tus datos

• GET /v1/sessions — de más reciente a más antigua, paginada por cursor, filtrable por type, since, folder y tag. Solo se devuelven las sesiones que terminaron de procesarse.
• 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 marca de tiempo y hablante identificado.
• GET /v1/sessions/:id/action-items — tareas pendientes estructuradas y un número de versión.
• GET /v1/sessions/:id/media — URLs firmadas de audio y video, válidas por una hora.
• POST /v1/sessions/search — búsqueda semántica, hasta 50 resultados, con filtros de etiqueta opcionales.
• POST /v1/sessions/bulk — hasta 50 sesiones en una sola llamada, con resúmenes y transcripciones. La forma rápida de importar el histórico.
• GET /v1/folders, GET /v1/sessions/stats — carpetas, y totales por tipo y plataforma.

Escribir datos

PATCH /v1/sessions/:id establece título, notas, etiquetas, favorito y tareas pendientes. Para las tareas pendientes, léelas primero y devuelve la versión que obtuviste — así una edición simultánea en la app de Wave se rechaza en lugar de sobrescribirse silenciosamente. POST /v1/folders y los endpoints de pertenencia a carpetas organizan las sesiones; las carpetas no son excluyentes, así que una sesión puede estar en varias.

DELETE /v1/sessions/:id es permanente y no es lo mismo que eliminar desde la app. Trátalo como algo irrecuperable.

Límites de uso

Cada token tiene un límite de 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 por 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 polling, deja que Wave te envíe un POST. En la sección Webhooks, haz clic en Add Webhook ("Añadir webhook"), ingresa una Endpoint URL ("URL del endpoint"; solo HTTPS, y se rechazan las URLs que resuelven a direcciones privadas), elige tus eventos y haz clic en Create Webhook. El Signing Secret ("Secreto de firma") se muestra una sola vez — guárdalo entonces. Puedes tener hasta cinco webhooks.

Hoy se pueden registrar tres eventos: Session Completed ("Sesión completada", se dispara una vez, después de que termine el procesamiento y el resumen sea consultable — el que la mayoría de las integraciones quiere), Session Updated ("Sesión actualizada") y Session Deleted ("Sesión eliminada").

Cada envío se firma 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.

Si un endpoint falla diez veces seguidas, Wave lo marca como Auto-disabled ("Desactivado automáticamente") y deja de enviarle datos. Arregla el endpoint y luego usa el botón de reactivar en la fila del webhook.

¿No tienes servidor? Usa el feed de eventos

Si no puedes alojar una URL pública, usa polling 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 hayas procesado, así reiniciar un script no vuelve a reproducir todo. Las páginas son de 50 elementos por defecto, con un máximo de 200, y el feed también incluye cambios en las tareas pendientes que las suscripciones de webhook no cubren. Requiere el permiso Read Event Feed.

El Wave CLI envuelve esto en wave events tail si prefieres no escribir tú mismo el bucle de polling.

Preguntas frecuentes