Wave Developer API

Die Wave Developer API ist eine REST-API über deine eigenen Aufnahmen. Richte deinen Code auf https://api.wave.co/v1 mit einem Token, den du in Wave erstellst, und du kannst Sitzungen auflisten, Zusammenfassungen und Transkripte lesen, nach Bedeutung suchen, Audio herunterladen, Titel und Aufgaben aktualisieren und einen Webhook erhalten, sobald eine Aufnahme fertig verarbeitet ist.

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

Einen Token erstellen

Sende ihn bei jeder Anfrage als Bearer-Token:

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

Die Token-Liste zeigt für jeden Token den Namen, das wave_api_-Präfix, das Erstellungsdatum und die letzte Nutzung. Das Papierkorb-Symbol öffnet Revoke Token ("Token widerrufen") – der Widerruf greift sofort, und alles, was diesen Token verwendet, erhält ab dann einen 401er-Fehler.

Berechtigungen

Berechtigungen gelten pro Token. Vergib nur so viele, wie unbedingt nötig.

Rufst du einen Endpunkt ohne die passende Berechtigung auf, erhältst du einen 403er-Fehler, der angibt, was fehlt.

Deine Daten lesen

• GET /v1/sessions – neueste zuerst, cursorbasierte Paginierung, filterbar nach type, since, folder und tag. Es werden nur vollständig verarbeitete Sitzungen zurückgegeben.
• GET /v1/sessions/:id – Titel, Dauer, Markdown-Zusammenfassung, Notizen, Tags, Favoritenstatus. Bei Telefonanrufen zusätzlich Richtung und Nummern.
• GET /v1/sessions/:id/transcript – ein durchgehender Transkripttext sowie zeitlich markierte, sprecherbezogene Segmente.
• GET /v1/sessions/:id/action-items – strukturierte Aufgaben und eine Versionsnummer.
• GET /v1/sessions/:id/media – signierte Audio- und Video-URLs, eine Stunde lang gültig.
• POST /v1/sessions/search – semantische Suche, bis zu 50 Ergebnisse, optionale Tag-Filter.
• POST /v1/sessions/bulk – bis zu 50 Sitzungen in einem Aufruf, inklusive Zusammenfassungen und Transkripten. Der schnellste Weg für einen Rückstands-Import.
• 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, Favoritenstatus und Aufgaben. Bei Aufgaben solltest du sie zuerst auslesen und die erhaltene Version zurücksenden – eine gleichzeitige Bearbeitung in der Wave-App wird dann abgelehnt statt stillschweigend überschrieben. POST /v1/folders und die Endpunkte zur Ordnerzugehörigkeit organisieren Sitzungen; Ordner schließen sich nicht gegenseitig aus, eine Sitzung kann also in mehreren liegen.

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

Teilen

Ein Token handelt in deinem Namen und kann daher die Sitzungen lesen, die andere Wave-Nutzer mit dir geteilt haben – im Rahmen der oben genannten Berechtigungen. GET /v1/shared-sessions listet sie auf, und GET /v1/shared-sessions/{owner_id}/{id} samt /transcript, /action-items und /media liest eine einzelne davon. Füge include=shared zu GET /v1/sessions hinzu, um sie in deine eigene Liste einzumischen; jede Zeile trägt dann access (owner oder shared) und bei geteilten Zeilen den Eigentümer. Geteilte Zeilen lassen sich nicht nach Ordner oder Tag filtern, geteilte Sitzungen sind nur lesbar, und die Suche erfasst nur deine eigenen Sitzungen.

Mit Share Sessions & Manage Access kann ein Token deine eigenen Sitzungen teilen: /v1/sessions/{id}/sharing zeigt, wer Zugriff hat, und die darunterliegenden Routen erstellen einen Einladungslink, versenden E-Mail-Einladungen (bis zu 10 Adressen pro Aufruf), stornieren eine ausstehende Einladung, entfernen eine Person oder setzen den Link zurück. Die vollständige Liste und die Limits findest du unter Sitzungen aus Claude, ChatGPT, der API und der CLI teilen.

Ratenbegrenzung

Jeder 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 429er-Fehler enthält Retry-After – warte ab, statt sofort erneut zu versuchen.

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

Webhooks

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

Derzeit gibt es drei registrierbare Events: Session Completed (löst einmal aus, nachdem die Verarbeitung abgeschlossen ist und die Zusammenfassung abrufbar ist – das von den meisten Integrationen bevorzugte Event), Session Updated und Session Deleted.

Jede Zustellung ist mit deinem Secret signiert und enthält die Header X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp und X-Wave-Webhook-Signature. Überprüfe die Signatur, bevor du einer Payload vertraust; die genaue zu signierende Zeichenfolge findest du in der API-Referenz.

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

Kein eigener Server? Nutze den Event-Feed

Falls du keine öffentliche URL hosten kannst, poll stattdessen. GET /v1/events liefert Events nach einem Cursor, den Wave pro Token verwaltet, und POST /v1/events/ack setzt ihn 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 zusätzlich Änderungen an Aufgaben, die Webhook-Abonnements nicht liefern. Dafür ist die Berechtigung Read Event Feed erforderlich.

Die Wave-CLI bündelt das Ganze in wave events tail, falls du die Polling-Schleife nicht selbst schreiben möchtest.

FAQ