Help Center

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/sessions

Die 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.

BerechtigungWas sie erlaubt
Read sessionsSessions auflisten und öffnen, Statistiken, Personen, Massenexport
Write sessions and action itemsTitel, Notizen, Zusammenfassung, Tags, Favorit und Action Items aktualisieren
Delete sessionsEine Session endgültig löschen
Search sessionsSemantische Suche über deine gesamte Bibliothek
Read transcriptsVollständige Transkripte mit Sprecherabschnitten
Access mediaSignierte Download-URLs für Audio und Video
Read accountKontoinformationen und Abonnementstatus
Manage webhooksWebhook-Endpunkte registrieren und verwalten
Read event feedDen Event-Feed abrufen und bestätigen
Read foldersOrdner auflisten und öffnen (funktioniert auch mit Read sessions)
Manage foldersOrdner erstellen, umbenennen, umfärben, anheften, neu anordnen und löschen sowie Sessions hinzufügen oder entfernen
Share sessions and manage accessEigene 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 nach type, since, folder, tag und person. Nur vollständig verarbeitete Sessions werden zurückgegeben. folder akzeptiert eine ID, einen Namen oder einen Pfad Parent/Child; ein übergeordneter Ordner schließt die Sessions seiner Unterordner ein, außer du übergibst include_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 eine parent_id (null auf der obersten Ebene), und GET /v1/folders?parent_id=none bzw. ?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 mit is_me markiert und steht an erster Stelle.
  • GET /v1/people/:id/sessions — die Aufnahmen einer Person, neueste zuerst, cursorbasierte Paginierung, filterbar nach type, from und to. Jede Zeile zeigt, wie lange die Person gesprochen hat, welchen Namen sie in diesem Transkript trägt, und ihre drei längsten Redebeiträge. Verwende me als 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 mit 202 und status: "fetching".
  • upload: mit einem content_type (optional auch filename und size_bytes). Wave antwortet mit 201 und einer signierten upload.url. Lade die Datei innerhalb von 15 Minuten per PUT dorthin hoch, mit exakt den mitgelieferten upload.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

War dieser Artikel hilfreich?

Brauchst du noch Hilfe?

Support per E-Mail

Auf dieser Seite