API développeur Wave

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

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

Créer un jeton

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.

Permissions

Les permissions sont propres à chaque jeton. Accordez le minimum nécessaire.

Si vous appelez un point de terminaison sans la permission correspondante, vous obtenez une erreur 403 indiquant 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 indiquent 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 aux intervenants.
• GET /v1/sessions/:id/action-items — actions à retenir structurées et un numéro de version.
• GET /v1/sessions/:id/media — URLs signées pour l'audio et la vidéo, 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. La méthode rapide pour rattraper 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 à retenir. Pour les actions à retenir, lisez-les d'abord et renvoyez la version obtenue — une modification simultanée dans l'application Wave est alors rejetée plutôt qu'écrasée silencieusement. POST /v1/folders et les points de terminaison d'appartenance à un dossier permettent d'organiser les sessions ; les dossiers ne sont pas exclusifs, une session peut donc figurer dans plusieurs à la fois.

DELETE /v1/sessions/:id est définitif et ne se comporte pas comme une suppression dans l'application. Considérez cette action comme irréversible.

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 erreur 429 inclut 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 renvoient des résultats identiques : utilisez plutôt les webhooks ou GET /v1/sessions?since= pour repérer ce qui est nouveau.

Webhooks

Plutôt que d'interroger l'API en boucle, faites en sorte que Wave vous envoie une requête 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 pointant 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 fois — enregistrez-le à ce moment-là. Vous pouvez créer jusqu'à cinq webhooks.

Trois événements sont disponibles aujourd'hui : Session Completed ("Session terminée", déclenché une seule fois, une fois le traitement terminé et le résumé disponible — celui que la plupart des intégrations utilisent), Session Updated ("Session mise à jour") et Session Deleted ("Session supprimée").

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

Si un point de terminaison échoue dix fois de suite, Wave le marque Auto-disabled ("Désactivé automatiquement") et arrête l'envoi. Corrigez le point de terminaison, puis utilisez le bouton de réactivation sur la ligne du webhook.

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

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

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

FAQ