Help Center

API développeur Wave

Créez un jeton à portée limitée et lisez, mettez à jour ou importez des sessions, transcriptions et actions à partir de votre propre code, avec recherche, export en masse et webhooks.

Dernière mise à jour:

L'API développeur Wave AI 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 les sessions, lire les résumés et transcriptions, effectuer une recherche par sens, télécharger l'audio, importer des enregistrements, mettre à jour les titres, résumés et actions, et recevoir un webhook dès qu'un enregistrement termine son traitement.

C'est gratuit sur tous les forfaits Wave, et cela ne touche jamais qu'à votre propre compte.

Créer un jeton

Dans l'application web Wave sur app.wave.co, allez dans Settings → Developers et ouvrez API tokens and webhooks ("Jetons API et webhooks") — 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 que vous reconnaîtrez plus tard, cochez les Permissions nécessaires, et cliquez sur Create token. Un jeton par intégration est bien plus simple à gérer qu'un jeton partagé.

Copiez le jeton depuis la fenêtre Token created. 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 revoir.")

Envoyez-le comme jeton bearer à 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_, ses permissions, ainsi que ses dates de création, de dernière utilisation et d'expiration. L'icône de corbeille demande Revoke this token? ("Révoquer ce jeton ?") — sélectionnez Revoke token et l'effet est immédiat ; tout ce qui utilise ce jeton reçoit alors une erreur 401.

Les jetons API expirent un an après leur création. Si une intégration qui fonctionnait bien depuis des mois renvoie soudain une erreur 401 invalid_token, vérifiez la date Expires dans la liste des jetons et créez-en un nouveau.

Permissions

Les permissions s'appliquent par jeton. Accordez le minimum nécessaire pour la tâche.

PermissionCe qu'elle autorise
Read sessionsLister et ouvrir les sessions, statistiques, personnes, export en masse
Write sessions and action itemsModifier titre, notes, résumé, tags, favori, actions
Delete sessionsSupprimer définitivement une session
Search sessionsRecherche sémantique dans votre bibliothèque
Read transcriptsTranscriptions complètes avec segments par intervenant
Access mediaURLs de téléchargement signées pour l'audio et la vidéo
Read accountInfos du compte et statut de l'abonnement
Manage webhooksEnregistrer et gérer les points de terminaison webhook
Read event feedRécupérer et acquitter le flux d'événements
Read foldersLister et ouvrir les dossiers (Read sessions fonctionne aussi)
Manage foldersCréer, renommer, recolorer, épingler, réordonner et supprimer des dossiers, et ajouter ou retirer des sessions
Share sessions and manage accessPartager vos sessions avec d'autres utilisateurs Wave, voir qui y a accès, et retirer des personnes
Import recordings (uses your import allowance)Importer de l'audio et de la vidéo dans Wave par lien ou par téléversement. Jamais incluse dans la permission d'écriture ; à cocher séparément

Appeler un endpoint sans la permission correspondante renvoie une erreur 403 indiquant ce qui manque.

Lire vos données

  • GET /v1/sessions — les plus récentes en premier, paginées par curseur, filtrables par type, since, folder, tag et person. Seules les sessions dont le traitement est terminé sont renvoyées. folder accepte un identifiant, un nom ou un chemin Parent/Child ; un dossier parent inclut les sessions de ses sous-dossiers, sauf si vous passez include_subfolders=false.
  • GET /v1/sessions/:id — titre, durée, résumé markdown, notes, tags, favori. Les appels téléphoniques contiennent aussi la direction et les numéros.
  • GET /v1/sessions/:id/transcript — une chaîne de transcription complète ainsi que 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 de tags optionnels.
  • POST /v1/sessions/bulk — jusqu'à 50 sessions en un seul appel, avec résumés et transcriptions. La méthode rapide pour rattraper un historique.
  • GET /v1/folders, GET /v1/folders/:id, GET /v1/sessions/stats — dossiers, et totaux par type et plateforme. Les dossiers s'imbriquent sur un seul niveau : chaque dossier a un parent_id (null au premier niveau), et GET /v1/folders?parent_id=none ou ?parent_id={id} liste un seul niveau.

Personnes

Les personnes sont les voix que vous avez enregistrées en tant que Voice ID. Elles ne requièrent que la permission Read Sessions, et sont en lecture seule.

  • GET /v1/people — toutes les personnes dont vous avez enregistré la voix, avec le nombre d'enregistrements où chacune apparaît et la date du dernier entendu. Votre propre voix est marquée is_me et apparaît en premier.
  • GET /v1/people/:id/sessions — les enregistrements d'une personne, les plus récents en premier, paginés par curseur, filtrables par type, from et to. Chaque ligne indique sa durée de parole, le nom qu'elle porte dans cette transcription, et ses trois plus longues répliques. Utilisez me comme id pour votre propre voix.
  • GET /v1/sessions?person=:id — la liste de sessions habituelle, restreinte aux enregistrements où cette personne apparaît.

Les échantillons vocaux ne sont jamais renvoyés, pas plus que les transcriptions complètes ; récupérez une transcription séparément si vous avez besoin de plus que les trois répliques. Si vous avez fusionné deux Voice ID dans Wave, l'ancien id renvoie une erreur 404 dont le champ merged_into indique l'id à utiliser. Tant que Wave indexe encore les personnes d'un compte, les comptages ne couvrent que les 1 000 enregistrements les plus récents et les réponses portent partial: true.

Écrire en retour

PATCH /v1/sessions/:id définit le titre, les notes, le résumé (markdown), les tags, le favori et les actions. Pour les actions, lisez-les d'abord et renvoyez la version reçue — une modification concurrente dans l'application Wave est alors rejetée plutôt qu'écrasée silencieusement. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id, ainsi que les endpoints d'appartenance aux dossiers (POST et DELETE /v1/sessions/:id/folders/:folderId) permettent d'organiser les sessions. Les dossiers ne sont pas exclusifs : une session peut se trouver dans plusieurs à la fois, et supprimer un dossier ne supprime pas les sessions qu'il contient. Passez parent_id à POST /v1/folders pour créer un sous-dossier, ou à PATCH /v1/folders/:id pour déplacer un dossier (null le ramène au premier niveau). Le parent doit être un dossier de premier niveau, et un dossier qui a des sous-dossiers ne peut pas être placé dans un autre ; dans les deux cas, la réponse est un 400 invalid_parent. Supprimer un parent fait passer ses sous-dossiers au premier niveau.

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

Importer des enregistrements

POST /v1/sessions/import crée une session à partir d'un fichier audio ou vidéo. Wave le transcrit et le résume exactement comme un fichier importé depuis l'application. Cela nécessite la permission Import recordings (uses your import allowance) (sessions:import). Envoyez l'un des éléments suivants :

  • source_url : un lien https public vers le fichier lui-même. Wave le télécharge (jusqu'à 2 Gio) et répond 202 avec status: "fetching".
  • upload : avec un content_type (et facultativement filename et size_bytes). Wave répond 201 avec une upload.url signée. Envoyez le fichier via PUT à cette adresse dans les 15 minutes, avec exactement les upload.headers fournis (jusqu'à 5 Gio). Le traitement démarre automatiquement une fois le téléversement terminé.

Vous pouvez aussi passer title, notes, tags, language et recorded_at. Ensuite, interrogez GET /v1/sessions/:id pour suivre processing_status, ou écoutez le 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"}'

Envoyez un en-tête Idempotency-Key pour sécuriser les nouvelles tentatives : répéter la même clé et le même corps renvoie la session d'origine au lieu d'en créer une seconde.

Formats pris en charge : MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG et MPEG-TS. Les imports partagent avec les applications Wave le quota d'import de votre compte : 12 par heure et 20 par jour (40 et 100 pour les clients payants ; moins pour les comptes de moins de deux jours). Au-delà, vous recevez une erreur 429 import_rate_limited, et un forfait gratuit sans minutes restantes reçoit une erreur 403 subscription_required.

Partage

Un jeton agit en votre nom, il peut donc lire les sessions que d'autres utilisateurs 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 routes /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 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 tag, les sessions partagées sont en lecture seule, et la recherche ne couvre que vos propres sessions.

Avec Share sessions and 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 Sharing Sessions from Claude, ChatGPT, the API and the 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 portent 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 donc les webhooks ou GET /v1/sessions?since= pour repérer les nouveautés.

Webhooks

Plutôt que d'interroger l'API, laissez Wave vous envoyer une requête POST. Dans la section Webhooks, cliquez sur Add webhook ("Ajouter un webhook"), saisissez une Endpoint URL (HTTPS uniquement, et les URLs pointant vers des adresses privées sont rejetées), choisissez vos Events, et cliquez sur Create webhook. Le Signing secret ("Secret de signature") n'est affiché qu'une seule fois — enregistrez-le immédiatement. Vous pouvez avoir jusqu'à cinq webhooks.

Les événements : Session completed (envoyé une fois, une fois le traitement terminé et le résumé interrogeable ; celui que la plupart des intégrations recherchent), Session updated, Action items updated (envoyé quand les actions sont écrites ou modifiées via l'API), et Session deleted. Vous pouvez aussi enregistrer un webhook depuis votre propre code avec POST /v1/webhooks (ou wave webhooks create).

Session completed peut contenir plus que le résumé. Lorsque vous créez un webhook avec POST /v1/webhooks, ou en modifiez un avec PATCH /v1/webhooks/:id, passez un objet include :

{ "include": { "summary": true, "transcript": true, "action_items": true } }

summary est activé par défaut ; transcript et action_items sont désactivés. Inclure la transcription nécessite un jeton avec la permission Read transcripts. Les transcriptions très longues sont tronquées à 200 000 caractères et marquées transcript_truncated: true ; récupérez le reste via GET /v1/sessions/:id/transcript. Les actions correspondent à celles présentes sur la session au moment où elle se termine ; si Wave en ajoute d'autres peu après, vous recevez un événement Action items updated. Les autres événements portent toujours la session simple.

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 à un contenu ; la chaîne exacte à signer figure dans la référence de l'API.

Wave ne garantit pas une seule livraison par événement. Un envoi qui expire (10 secondes) ou renvoie un code non-2xx est retenté jusqu'à trois fois avec un court délai croissant — environ 10 secondes, puis une minute, puis cinq minutes — et le même événement peut légitimement arriver plus d'une fois. Rendez votre gestionnaire idempotent : basez-vous sur X-Wave-Webhook-Id, ignorez un id 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 Turned off automatically ("Désactivé automatiquement") et cesse d'envoyer. Corrigez le point de terminaison, puis sélectionnez Turn webhook back on ("Réactiver le webhook") sur la ligne du webhook.

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 après un curseur que Wave suit par jeton, et POST /v1/events/ack le fait avancer une fois que vous les avez traités, afin qu'un redémarrage de script ne rejoue pas tout l'historique. Les pages affichent 50 éléments par défaut, avec un maximum de 200, et le flux inclut aussi les modifications d'actions. Nécessite la permission Read event feed.

Le CLI Wave intègre ceci dans wave events tail si vous préférez ne pas écrire la boucle d'interrogation vous-même.

FAQ

Cet article vous a-t-il été utile ?

Besoin d'aide supplémentaire ?

Écrire au support

Sur cette page