Wave Developer API
Erstelle ein eingeschränktes Token und lies, aktualisiere oder importiere Wave-Sessions, Transkripte und Action Items direkt aus deinem eigenen Code – mit Suche, Massenexport und Webhooks.
Zuletzt aktualisiert:
Die Wave AI 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, Aufnahmen importieren, Titel, Zusammenfassungen und Action Items aktualisieren sowie dir per Webhook mitteilen lassen, sobald eine Aufnahme fertig verarbeitet ist.
Die API ist in jedem Wave-Plan kostenlos und greift ausschließlich auf dein eigenes Konto zu.
Ein Token erstellen
Gehe in der Wave-Web-App unter app.wave.co zu Settings → Developers ("Einstellungen → Entwickler") und öffne API tokens and webhooks ("API-Token und Webhooks") — oder direkt zu app.wave.co/settings/integrations/api.
Klicke unter API tokens ("API-Token") auf Create token ("Token erstellen").
Gib ihm einen Token name ("Token-Name"), den du später wiedererkennst, hake die benötigten Permissions ("Berechtigungen") an und klicke auf Create token. Ein Token pro Integration lässt sich deutlich leichter verwalten als ein gemeinsames Token für alles.
Kopiere das Token aus dem Dialog Token created ("Token erstellt"). Wave zeigt es nur einmal an: Copy this token now. You will not be able to see it again. ("Kopiere dieses Token jetzt. Du wirst es danach nicht mehr sehen können.")
Sende es bei jeder Anfrage als Bearer-Token mit:
curl -H "Authorization: Bearer wave_api_xxx..." \
https://api.wave.co/v1/sessionsDie Token-Liste zeigt zu jedem Token den Namen, das Präfix wave_api_, die Berechtigungen sowie Erstellungs-, letztes Nutzungs- und Ablaufdatum. Das Papierkorb-Symbol fragt Revoke this token? ("Dieses Token widerrufen?") — wähle Revoke token ("Token widerrufen") und die Änderung gilt sofort; alles, was dieses Token verwendet, erhält ab dann einen 401er.
API-Token laufen ein Jahr nach ihrer Erstellung ab. Wenn eine Integration, die monatelang problemlos lief, plötzlich 401 invalid_token zurückgibt, prüfe das Datum unter Expires ("Läuft ab") in der Token-Liste und erstelle ein neues Token.
Berechtigungen
Berechtigungen gelten pro Token. Vergib so wenige wie möglich, aber so viele wie nötig.
| Berechtigung | Was sie erlaubt |
|---|---|
| Read sessions | Sessions auflisten und öffnen, Statistiken, Personen, Massenexport |
| Write sessions and action items | Titel, Notizen, Zusammenfassung, Tags, Favorit und Action Items aktualisieren |
| Delete sessions | Eine Session endgültig löschen |
| Search sessions | Semantische Suche über deine gesamte Bibliothek |
| Read transcripts | Vollständige Transkripte mit Sprecherabschnitten |
| Access media | Signierte Download-URLs für Audio und Video |
| Read account | Kontoinformationen und Abonnementstatus |
| Manage webhooks | Webhook-Endpunkte registrieren und verwalten |
| Read event feed | Den Event-Feed abrufen und bestätigen |
| Read folders | Ordner auflisten und öffnen (funktioniert auch mit Read sessions) |
| Manage folders | Ordner erstellen, umbenennen, umfärben, anheften, neu anordnen und löschen sowie Sessions hinzufügen oder entfernen |
| Share sessions and manage access | Eigene Sessions mit anderen Wave-Nutzern teilen, sehen, wer Zugriff hat, und Personen entfernen |
| Import recordings (uses your import allowance) | Audio und Video per Link oder Upload in Wave importieren. Nie in der Schreibberechtigung enthalten — muss separat angehakt werden |
Rufst du einen Endpunkt ohne passende Berechtigung auf, erhältst du einen 403, der benennt, was fehlt.
Daten lesen
GET /v1/sessions— neueste zuerst, cursorbasierte Paginierung, filterbar nachtype,since,folder,tagundperson. Nur vollständig verarbeitete Sessions werden zurückgegeben.folderakzeptiert eine ID, einen Namen oder einen PfadParent/Child; ein übergeordneter Ordner schließt die Sessions seiner Unterordner ein, außer du übergibstinclude_subfolders=false.GET /v1/sessions/:id— Titel, Dauer, Markdown-Zusammenfassung, Notizen, Tags, Favorit. Telefonanrufe enthalten zusätzlich Richtung und Nummern.GET /v1/sessions/:id/transcript— ein zusammenhängender Transkript-String plus zeitlich markierte, sprecherbeschriftete Abschnitte.GET /v1/sessions/:id/action-items— strukturierte Action Items 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 Sessions in einem Aufruf, inklusive Zusammenfassungen und Transkripten. Der schnellste Weg für einen Datenabgleich im Nachhinein.GET /v1/folders,GET /v1/folders/:id,GET /v1/sessions/stats— Ordner sowie Gesamtzahlen nach Typ und Plattform. Ordner sind eine Ebene tief verschachtelbar: Jeder Ordner hat eineparent_id(nullauf der obersten Ebene), undGET /v1/folders?parent_id=nonebzw.?parent_id={id}listet eine Ebene auf.
Personen
Personen sind die Stimmen, die du als Voice IDs gespeichert hast. Dafür reicht die Berechtigung Read Sessions, und die Daten sind nur lesbar.
GET /v1/people— jeder, für den du eine Stimme gespeichert hast, inklusive Anzahl der Aufnahmen und letztem Vorkommen. Deine eigene Stimme ist mitis_memarkiert und steht an erster Stelle.GET /v1/people/:id/sessions— die Aufnahmen einer Person, neueste zuerst, cursorbasierte Paginierung, filterbar nachtype,fromundto. Jede Zeile zeigt, wie lange die Person gesprochen hat, welchen Namen sie in diesem Transkript trägt, und ihre drei längsten Redebeiträge. Verwendemeals ID für deine eigene Stimme.GET /v1/sessions?person=:id— die normale Sessionliste, eingegrenzt auf Aufnahmen, in denen diese Person vorkommt.
Sprachproben werden nie zurückgegeben, ebenso wenig vollständige Transkripte; rufe ein Transkript separat ab, wenn du mehr als die drei Zeilen brauchst. Hast du zwei Voice IDs in Wave zusammengeführt, liefert die alte ID einen 404, dessen merged_into die zu verwendende ID nennt. Solange Wave die Personen eines Kontos noch indexiert, decken Zählungen nur die neuesten 1.000 Aufnahmen ab, und Antworten tragen partial: true.
Daten zurückschreiben
PATCH /v1/sessions/:id setzt Titel, Notizen, Zusammenfassung (Markdown), Tags, Favorit und Action Items. Lies Action Items für Updates zuerst ein und gib die erhaltene Version zurück — eine gleichzeitige Bearbeitung in der Wave-App wird dann abgelehnt, statt stillschweigend überschrieben zu werden. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id sowie die Endpunkte für Ordnermitgliedschaft (POST und DELETE /v1/sessions/:id/folders/:folderId) organisieren Sessions. Ordner schließen sich nicht gegenseitig aus, eine Session kann also in mehreren liegen, und das Löschen eines Ordners löscht nicht die darin enthaltenen Sessions. Übergib parent_id an POST /v1/folders, um einen Unterordner anzulegen, oder an PATCH /v1/folders/:id, um einen Ordner zu verschieben (null bringt ihn zurück auf die oberste Ebene). Der übergeordnete Ordner muss auf der obersten Ebene liegen, und ein Ordner mit Unterordnern kann nicht in einen anderen verschoben werden; beides liefert einen 400 invalid_parent. Wird ein übergeordneter Ordner gelöscht, wandern seine Unterordner auf die oberste Ebene.
DELETE /v1/sessions/:id ist endgültig und nicht dasselbe wie das Löschen in der App. Behandle es als nicht wiederherstellbar.
Aufnahmen importieren
POST /v1/sessions/import erstellt eine Session aus einer Audio- oder Videodatei. Wave transkribiert und fasst sie genauso zusammen wie eine in der App importierte Datei. Dafür ist die Berechtigung Import recordings (uses your import allowance) (sessions:import) nötig. Sende eines von beidem:
source_url: ein öffentlicher https-Link direkt zur Datei. Wave lädt sie herunter (bis zu 2 GiB) und antwortet mit202undstatus: "fetching".upload: mit einemcontent_type(optional auchfilenameundsize_bytes). Wave antwortet mit201und einer signiertenupload.url. Lade die Datei innerhalb von 15 Minuten per PUT dorthin hoch, mit exakt den mitgeliefertenupload.headers(bis zu 5 GiB). Die Verarbeitung startet automatisch, sobald der Upload abgeschlossen ist.
Du kannst außerdem title, notes, tags, language und recorded_at mitgeben. Frage danach GET /v1/sessions/:id auf processing_status ab oder warte auf den 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"}'Sende einen Idempotency-Key-Header, um Wiederholungen sicher zu machen: Wiederholst du denselben Key und Body, erhältst du die ursprüngliche Session zurück statt eines zweiten Imports.
Unterstützte Formate: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG und MPEG-TS. Importe teilen sich das Importkontingent deines Kontos mit den Wave-Apps: 12 pro Stunde und 20 pro Tag (40 und 100 für zahlende Kunden; weniger für Konten, die jünger als zwei Tage sind). Darüber hinaus erhältst du einen 429 import_rate_limited, und ein kostenloser Plan ohne verbleibende Minuten erhält einen 403 subscription_required.
Teilen
Ein Token handelt in deinem Namen und kann daher die Sessions 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. 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 Sessions sind nur lesbar, und die Suche deckt nur deine eigenen Sessions ab.
Mit Share sessions and manage access kann ein Token deine eigenen Sessions 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 Sharing Sessions from Claude, ChatGPT, the API and the CLI.
Ratenlimits
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 enthält Retry-After — warte entsprechend, statt sofort erneut zu versuchen.
Wiederholst du dieselbe Suchanfrage mehr als zehnmal pro Stunde, gibt es ebenfalls einen 429. Identische Suchanfragen liefern identische Ergebnisse — nutze stattdessen Webhooks oder GET /v1/sessions?since=, um Neues zu finden.
Webhooks
Statt zu pollen, kannst du Wave per POST an dich senden lassen. 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 ("Webhook erstellen"). Das Signing secret ("Signaturgeheimnis") wird nur einmal angezeigt — speichere es sofort. Du kannst bis zu fünf Webhooks einrichten.
Die Events: Session completed (wird einmal gesendet, nachdem die Verarbeitung abgeschlossen ist und die Zusammenfassung abrufbar ist; das Event, das die meisten Integrationen nutzen), Session updated, Action items updated (wird gesendet, wenn Action Items über die API geschrieben oder bearbeitet werden) und Session deleted. Du kannst einen Webhook auch direkt aus deinem Code registrieren, mit POST /v1/webhooks (oder wave webhooks create).
Session completed kann mehr als nur die Zusammenfassung enthalten. Wenn du mit POST /v1/webhooks einen Webhook erstellst oder ihn mit PATCH /v1/webhooks/:id änderst, gib ein include-Objekt an:
{ "include": { "summary": true, "transcript": true, "action_items": true } }summary ist standardmäßig aktiviert; transcript und action_items sind es nicht. Das Transkript einzuschließen erfordert ein Token mit Read transcripts. Sehr lange Transkripte werden bei 200.000 Zeichen abgeschnitten und mit transcript_truncated: true markiert; den Rest erhältst du über GET /v1/sessions/:id/transcript. Die Action Items entsprechen dem Stand bei Abschluss der Session; fügt Wave kurz darauf weitere hinzu, erhältst du ein Action items updated-Event. Andere Events enthalten immer die einfache Session.
Jede Zustellung ist mit deinem Geheimnis signiert und kommt mit den Headern X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp und X-Wave-Webhook-Signature an. Prüfe die Signatur, bevor du einer Payload vertraust; den genauen zu signierenden String findest du in der API-Referenz.
Wave garantiert keine einmalige Zustellung pro Event. Eine Zustellung, die ein Timeout erreicht (10 Sekunden) oder einen Status außerhalb des 2xx-Bereichs zurückgibt, wird bis zu dreimal mit kurzem Backoff wiederholt — etwa nach 10 Sekunden, dann einer Minute, dann fünf Minuten — und dasselbe Event kann durchaus mehrfach eintreffen. Mache deinen Handler idempotent: verwende X-Wave-Webhook-Id als Schlüssel, ignoriere bereits verarbeitete IDs und antworte zügig mit einem 2xx. Ein Endpunkt, der länger als dieses Zeitfenster ausfällt, verliert die verpassten Events — nutze in diesem Fall den unten beschriebenen Event-Feed, um aufzuholen.
Schlägt ein Endpunkt zehnmal in Folge fehl, markiert Wave ihn als Turned off automatically ("Automatisch deaktiviert") und stellt die Zustellung ein. Behebe das Problem am Endpunkt und wähle dann in der Webhook-Zeile Turn webhook back on ("Webhook wieder aktivieren").
Kein eigener Server? Nutze den Event-Feed
Kannst du keine öffentliche URL hosten, polle stattdessen. GET /v1/events liefert Events ab einem Cursor, den Wave pro Token führt, und POST /v1/events/ack setzt ihn weiter, sobald du die Events verarbeitet hast — so wiederholt ein Neustart eines Skripts nicht alles von vorn. Seiten umfassen standardmäßig 50 Einträge und maximal 200, und der Feed enthält auch Änderungen an Action Items. Erfordert die Berechtigung Read event feed.
Die Wave CLI kapselt das in wave events tail, falls du die Polling-Schleife nicht selbst schreiben möchtest.
FAQ
api.wave.co/reference enthält jeden Endpunkt, jeden Parameter und jede Antwortstruktur mit Live-Beispielen. api.wave.co/llms.txt bietet denselben Inhalt als reinen Text — füge ihn in einen KI-Assistenten ein und lass ihn die Integration für dich schreiben.
Immer als JSON, mit einem code und einer message. Die häufigsten: 401 invalid_token (abgelaufen, widerrufen oder falsch eingegeben), 403 insufficient_scope (dem Token fehlt eine Berechtigung) und 429 (Ratenlimit erreicht).
Nur solche, die andere mit dir geteilt haben. Ein Token ist an das Konto gebunden, das es erstellt hat: Es liefert die Sessions dieses Kontos sowie Sessions, die andere Wave-Nutzer mit diesem Konto geteilt haben — nur lesend.
War dieser Artikel hilfreich?
Brauchst du noch Hilfe?
Das Wave Agents Toolkit: Verbinde deine Daten mit jedem anderen Tool
Drei Wege, deine Wave-Aufnahmen in andere Tools zu bringen: MCP für KI-Assistenten, eine REST-API für eigenen Code und ein CLI für das Terminal.
Sitzungen aus Claude, ChatGPT, der API und der CLI teilen
Lies die Sitzungen, die andere mit dir geteilt haben, und teile deine eigenen – aus einem KI-Assistenten, deinem eigenen Code oder dem Terminal.