API développeur Wave

Créez un jeton à accès limité et consultez ou mettez à jour vos sessions, transcriptions et actions à partir de votre propre code — avec recherche, export groupé et webhooks.

L'API développeur Wave est une API REST donnant accès à vos propres enregistrements. Pointez votre code vers https://api.wave.co/v1 avec un jeton que vous créez dans Wave, et vous pouvez lister vos sessions, lire les résumés et transcriptions, effectuer une recherche par sens, télécharger l'audio, mettre à jour les titres et les actions, et recevoir un webhook dès qu'un enregistrement termine son traitement.

Elle est gratuite sur toutes les formules Wave, et n'accède jamais qu'à votre propre compte.

Créer un jeton

Dans l'application web de Wave sur app.wave.co, ouvrez votre profil, sélectionnez l'onglet Integrations et ouvrez Developer API — ou allez directement sur app.wave.co/settings/integrations/api.

Sous API Tokens, cliquez sur Create Token ("Créer un jeton").

Donnez-lui un Token Name ("Nom du jeton") que vous reconnaîtrez plus tard, cochez les Permissions dont il a besoin, puis cliquez sur Create Token. Un jeton par intégration est bien plus facile à gérer qu'un jeton partagé.

Copiez le jeton. Wave ne l'affiche qu'une seule fois : Copy this token now. You will not be able to see it again. ("Copiez ce jeton maintenant. Vous ne pourrez plus le voir ensuite.")

Envoyez-le comme jeton porteur (bearer token) à chaque requête :

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

La liste des jetons affiche le nom de chacun, son préfixe wave_api_, sa date de création et sa dernière utilisation. L'icône de corbeille ouvre Revoke Token ("Révoquer le jeton") — la révocation prend effet immédiatement, et tout ce qui utilise ce jeton reçoit alors une erreur 401.

Les jetons API expirent un an après leur création, et cette date d'expiration n'apparaît pas dans la liste des jetons. Si une intégration qui fonctionnait bien depuis des mois renvoie soudainement une erreur 401 invalid_token, créez un nouveau jeton.

Permissions

Les permissions s'appliquent par jeton. Accordez le strict minimum nécessaire.

Permission	Ce qu'elle permet
Read Sessions	Lister et ouvrir des sessions, statistiques, dossiers, export groupé
Search Sessions	Recherche sémantique dans votre bibliothèque
Read Transcripts	Transcriptions complètes avec segments par intervenant
Access Media	URLs de téléchargement signées pour l'audio et la vidéo
Write Sessions & Action Items	Mise à jour du titre, des notes, des tags, des favoris, des actions
Delete Sessions	Suppression définitive d'une session
Manage Folders	Création de dossiers, ajout et retrait de sessions
Manage Webhooks	Enregistrement et gestion des points de terminaison webhook
Read Event Feed	Récupération et validation du flux d'événements
Read Account	Informations de compte et statut d'abonnement
Share Sessions & Manage Access	Partager vos sessions avec d'autres utilisateurs de Wave, voir qui y a accès, et retirer des personnes

Appeler un point de terminaison sans la permission correspondante renvoie une erreur 403 précisant ce qui manque.

Lire vos données

GET /v1/sessions — du plus récent au plus ancien, pagination par curseur, filtrable par type, since, folder et tag. Seules les sessions dont le traitement est terminé sont renvoyées.
GET /v1/sessions/:id — titre, durée, résumé au format markdown, notes, tags, favori. Les appels téléphoniques incluent aussi la direction et les numéros.
GET /v1/sessions/:id/transcript — une transcription sous forme de texte brut, plus des segments horodatés et attribués à chaque intervenant.
GET /v1/sessions/:id/action-items — des actions structurées et un numéro de version.
GET /v1/sessions/:id/media — URLs audio et vidéo signées, valables une heure.
POST /v1/sessions/search — recherche sémantique, jusqu'à 50 résultats, filtres par tag facultatifs.
POST /v1/sessions/bulk — jusqu'à 50 sessions en un seul appel, avec résumés et transcriptions. Le moyen le plus rapide de récupérer l'historique.
GET /v1/folders, GET /v1/sessions/stats — dossiers, et totaux par type et par plateforme.

Écrire des données

PATCH /v1/sessions/:id permet de définir le titre, les notes, les tags, le favori et les actions. Pour les actions, lisez-les d'abord et renvoyez la version obtenue — une modification concurrente dans l'application Wave est alors rejetée plutôt qu'écrasée silencieusement. POST /v1/folders et les points de terminaison d'appartenance aux dossiers permettent d'organiser les sessions ; les dossiers ne sont pas exclusifs, une session peut donc se trouver dans plusieurs à la fois.

DELETE /v1/sessions/:id est définitif et n'équivaut pas à une suppression depuis l'application. Considérez-le comme irréversible.

Partage

Un jeton agit en votre nom : il peut donc lire les sessions que d'autres utilisateurs de Wave ont partagées avec vous, selon les permissions ci-dessus. GET /v1/shared-sessions les liste, et GET /v1/shared-sessions/{owner_id}/{id} ainsi que ses variantes /transcript, /action-items et /media permettent d'en lire une. Ajoutez include=shared à GET /v1/sessions pour les mélanger à votre propre liste ; chaque ligne porte alors un champ access (owner ou shared) et, pour les lignes partagées, le propriétaire. Les lignes partagées ne peuvent pas être filtrées par dossier ou par tag, les sessions partagées sont en lecture seule, et la recherche ne porte que sur vos propres sessions.

Avec la permission Share Sessions & Manage Access, un jeton peut partager vos propres sessions : /v1/sessions/{id}/sharing montre qui y a accès, et les routes associées permettent de créer un lien d'invitation, d'inviter par e-mail (jusqu'à 10 adresses par appel), d'annuler une invitation en attente, de retirer une personne, ou de réinitialiser le lien. Voir Partager des sessions depuis Claude, ChatGPT, l'API et la CLI pour la liste complète et les limites.

Limites de débit

Chaque jeton dispose de 60 requêtes par minute et 10 000 requêtes par jour. Les réponses incluent les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, et une réponse 429 inclut un Retry-After — patientez plutôt que de réessayer immédiatement.

Répéter la même requête de recherche plus de dix fois par heure renvoie aussi une erreur 429. Des recherches identiques donnent des résultats identiques : utilisez plutôt les webhooks ou GET /v1/sessions?since= pour repérer les nouveautés.

Webhooks

Plutôt que d'interroger l'API en boucle, laissez Wave vous envoyer des notifications en POST. Dans la section Webhooks, cliquez sur Add Webhook ("Ajouter un webhook"), saisissez une Endpoint URL ("URL du point de terminaison", HTTPS uniquement — les URLs résolvant vers des adresses privées sont rejetées), choisissez vos événements, puis cliquez sur Create Webhook. Le Signing Secret ("secret de signature") n'est affiché qu'une seule fois — conservez-le à ce moment-là. Vous pouvez avoir jusqu'à cinq webhooks.

Trois événements sont disponibles aujourd'hui : Session Completed ("Session terminée", déclenché une fois, après la fin du traitement et dès que le résumé est consultable — celui que la plupart des intégrations recherchent), Session Updated ("Session mise à jour"), et Session Deleted ("Session supprimée").

Chaque envoi est signé avec votre secret et arrive avec les en-têtes X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp et X-Wave-Webhook-Signature. Vérifiez la signature avant de faire confiance à une charge utile ; la chaîne exacte à signer figure dans la référence de l'API.

Wave ne garantit pas un envoi unique par événement. Un envoi qui expire (10 secondes) ou renvoie un code hors 2xx est retenté jusqu'à trois fois selon un intervalle croissant — environ 10 secondes, puis une minute, puis cinq minutes — et un même événement peut donc légitimement arriver plusieurs fois. Rendez votre gestionnaire idempotent : basez-vous sur X-Wave-Webhook-Id, ignorez un identifiant déjà traité, et renvoyez rapidement un code 2xx. Un point de terminaison hors service plus longtemps que cette fenêtre perd les événements manqués : utilisez alors le flux d'événements ci-dessous pour rattraper le retard.

Si un point de terminaison échoue dix fois de suite, Wave le marque Auto-disabled ("Désactivé automatiquement") et cesse d'y envoyer des données. Corrigez le point de terminaison, puis utilisez le bouton de réactivation sur la ligne du webhook concerné.

Pas de serveur ? Utilisez le flux d'événements

Si vous ne pouvez pas héberger d'URL publique, interrogez l'API à la place. GET /v1/events renvoie les événements survenus après un curseur que Wave suit pour chaque jeton, et POST /v1/events/ack fait avancer ce curseur une fois les événements traités, pour qu'un redémarrage de script ne rejoue pas tout l'historique. Les pages contiennent 50 éléments par défaut, avec un maximum de 200, et le flux inclut aussi les modifications d'actions que les abonnements webhook ne couvrent pas. Nécessite la permission Read Event Feed.

La CLI Wave encapsule tout cela dans la commande wave events tail, si vous préférez ne pas écrire vous-même la boucle d'interrogation.