Wave Developer API

Die Wave Developer API ist eine REST-API für deine eigenen Aufnahmen. Richte deinen Code auf https://api.wave.co/v1 mit einem Token, das du in Wave erstellst, und du kannst Sessions auflisten, Zusammenfassungen und Transkripte lesen, inhaltlich suchen, Audio herunterladen, Titel und Action Items aktualisieren und einen Webhook erhalten, sobald eine Aufnahme fertig verarbeitet ist.

Es ist in jedem Wave-Plan kostenlos enthalten und greift ausschließlich auf dein eigenes Konto zu.

Ein Token erstellen

Sende es bei jeder Anfrage als Bearer-Token:

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

Die Token-Liste zeigt zu jedem Token den Namen, das wave_api_-Präfix, das Erstellungsdatum und die letzte Verwendung. Über das Papierkorb-Symbol öffnest du Revoke Token ("Token widerrufen") – der Widerruf wirkt sofort, und alles, was dieses Token verwendet, erhält ab dann einen 401-Fehler.

Berechtigungen

Berechtigungen gelten pro Token. Vergib immer nur die nötigsten.

Rufst du einen Endpunkt ohne die passende Berechtigung auf, erhältst du einen 403-Fehler, der die fehlende Berechtigung benennt.

Deine Daten lesen

• GET /v1/sessions — neueste zuerst, per Cursor paginiert, filterbar nach type, since, folder und tag. Es werden nur Sessions zurückgegeben, deren Verarbeitung abgeschlossen ist.
• GET /v1/sessions/:id — Titel, Dauer, Markdown-Zusammenfassung, Notizen, Tags, Favorit. Bei Telefonanrufen zusätzlich Richtung und Rufnummern.
• GET /v1/sessions/:id/transcript — ein durchgehender Transkript-String sowie zeitgestempelte, sprecherbeschriftete Segmente.
• GET /v1/sessions/:id/action-items — strukturierte Action Items und eine Versionsnummer.
• GET /v1/sessions/:id/media — signierte Audio- und Video-URLs, eine Stunde gültig.
• POST /v1/sessions/search — semantische Suche, bis zu 50 Ergebnisse, optionale Tag-Filter.
• POST /v1/sessions/bulk — bis zu 50 Sessions in einem Aufruf, mit Zusammenfassungen und Transkripten. Der schnelle Weg, um Altbestände nachzuladen.
• GET /v1/folders, GET /v1/sessions/stats — Ordner sowie Gesamtzahlen nach Typ und Plattform.

Daten zurückschreiben

PATCH /v1/sessions/:id setzt Titel, Notizen, Tags, Favorit und Action Items. Bei Action Items solltest du sie zuerst lesen und die erhaltene Version zurücksenden – eine gleichzeitige Bearbeitung in der Wave-App wird dann abgelehnt, statt stillschweigend überschrieben zu werden. POST /v1/folders und die Endpunkte für die Ordnerzugehörigkeit organisieren Sessions; Ordner schließen sich nicht gegenseitig aus, eine Session kann also in mehreren liegen.

DELETE /v1/sessions/:id ist endgültig und nicht dasselbe wie das Löschen in der App. Behandle es als nicht wiederherstellbar.

Rate-Limits

Jedes Token erhält 60 Anfragen pro Minute und 10.000 Anfragen pro Tag. Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset, und ein 429-Fehler enthält Retry-After – warte dann, statt sofort erneut zu versuchen.

Wird dieselbe Suchanfrage mehr als zehnmal pro Stunde wiederholt, gibt es ebenfalls einen 429-Fehler. Identische Suchanfragen liefern identische Ergebnisse, nutze also Webhooks oder GET /v1/sessions?since=, um Neues zu finden.

Webhooks

Statt zu pollen, kannst du Wave an dich POSTen lassen. Klicke im Bereich Webhooks auf Add Webhook ("Webhook hinzufügen"), trage eine Endpoint URL ("Endpunkt-URL") ein (nur HTTPS, URLs, die zu privaten Adressen auflösen, werden abgelehnt), wähle deine Events aus und klicke auf Create Webhook. Das Signing Secret ("Signatur-Geheimnis") wird nur einmal angezeigt – speichere es dann sofort. Du kannst bis zu fünf Webhooks anlegen.

Derzeit sind drei Events verfügbar: Session Completed (feuert einmal, sobald die Verarbeitung abgeschlossen und die Zusammenfassung abrufbar ist – das, was die meisten Integrationen wollen), Session Updated und Session Deleted.

Jede Zustellung wird mit deinem Secret signiert und enthält die Header X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp und X-Wave-Webhook-Signature. Prüfe die Signatur, bevor du einer Payload vertraust; den genauen zu signierenden String findest du in der API-Referenz.

Schlägt ein Endpunkt zehnmal in Folge fehl, markiert Wave ihn als Auto-disabled ("automatisch deaktiviert") und stellt die Zustellung ein. Behebe das Problem am Endpunkt und nutze dann die Schaltfläche zum erneuten Aktivieren in der Webhook-Zeile.

Kein Server? Nutze den Event-Feed

Falls du keine öffentliche URL hosten kannst, pollst du stattdessen. GET /v1/events liefert Events nach einem Cursor, den Wave pro Token verfolgt, und POST /v1/events/ack schaltet diesen weiter, sobald du die Events verarbeitet hast – ein Neustart deines Skripts spielt so nicht alles erneut ab. Seiten umfassen standardmäßig 50 Einträge und maximal 200, und der Feed enthält zudem Änderungen an Action Items, die Webhook-Abonnements nicht liefern. Erfordert die Berechtigung Read Event Feed.

Die Wave CLI bildet das über wave events tail ab, falls du die Polling-Schleife nicht selbst schreiben möchtest.

FAQ