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, 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 es inmediata, y cualquier proceso que use ese token empezará a recibir un error 401.

Permisos

Los permisos son por token. Otorga solo los que hagan falta.

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

Leer tus datos

• GET /v1/sessions — de más reciente a más antigua, con paginación 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 etiquetados por interlocutor.
• GET /v1/sessions/:id/action-items — tareas 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 más rápida de importar datos históricos.
• 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. Para las tareas, 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 sin aviso. POST /v1/folders y los endpoints de pertenencia a carpetas organizan las sesiones; las carpetas no son exclusivas, así que una sesión puede estar en varias a la vez.

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

Compartir

Un token actúa en tu nombre, así que puede leer las sesiones que otros usuarios de Wave compartieron contigo con los permisos indicados 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 en concreto. Añade include=shared a GET /v1/sessions para mezclarlas con tu propia lista; cada fila lleva entonces access (owner o shared) y, para las compartidas, el propietario. Las filas compartidas no se pueden filtrar por carpeta ni etiqueta, las sesiones compartidas son de solo lectura, y la búsqueda cubre solo tus propias sesiones.

Con Share Sessions & Manage Access, un token puede compartir tus propias sesiones: /v1/sessions/{id}/sharing muestra quién tiene acceso, y las rutas debajo de esta crean un enlace de invitación, 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 frecuencia

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 en lugar de reintentar 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 sondeo (polling), haz que Wave te envíe datos por POST. En la sección Webhooks, haz clic en Add Webhook ("Añadir webhook"), introduce una Endpoint URL ("URL del endpoint") (solo HTTPS, y las URLs que resuelvan a direcciones privadas se rechazan), 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, cuando termina el procesamiento y el resumen ya se puede consultar; es el que la mayoría de las integraciones quiere), Session Updated ("Sesión actualizada") y Session Deleted ("Sesión eliminada").

Cada entrega va 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 el contenido; la cadena exacta que hay que 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 reactivación en la fila del webhook.

¿No tienes servidor? Usa el feed de eventos

Si no puedes alojar una URL pública, usa sondeo 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, de modo que reiniciar un script no repita todo desde el principio. Las páginas son de 50 por defecto y un máximo de 200, y el feed también incluye cambios en las tareas que las suscripciones de webhook no cubren. Requiere el permiso Read Event Feed.

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

Preguntas frecuentes