Wave Developer API
Create a scoped token and read, update, or import Wave sessions, transcripts, and action items from your own code, with search, bulk export, and webhooks.
Last updated:
The Wave AI Developer API is a REST API over your own recordings. Point your code at https://api.wave.co/v1 with a token you create in Wave, and you can list sessions, read summaries and transcripts, search by meaning, download audio, import recordings, update titles, summaries, and action items, and get pushed a webhook the moment a recording finishes processing.
It's free on every Wave plan, and it only ever reaches your own account.
Create a token
In the Wave web app at app.wave.co, go to Settings → Developers and open API tokens and webhooks — or go straight to app.wave.co/settings/integrations/api.
Under API tokens, click Create token.
Give it a Token name you'll recognize later, tick the Permissions it needs, and click Create token. One token per integration is far easier to manage than one shared token.
Copy the token from the Token created dialog. Wave shows it once: Copy this token now. You will not be able to see it again.
Send it as a bearer token on every request:
curl -H "Authorization: Bearer wave_api_xxx..." \
https://api.wave.co/v1/sessionsThe token list shows each token's name, its wave_api_ prefix, its permissions, and when it was created, last used, and expires. The trash icon asks Revoke this token? — select Revoke token and it takes effect immediately; anything using that token starts getting a 401.
API tokens expire one year after they're created. If an integration that ran fine for months suddenly returns 401 invalid_token, check the Expires date in the token list and create a fresh token.
Permissions
Permissions are per token. Grant the fewest that do the job.
| Permission | What it allows |
|---|---|
| Read sessions | List and open sessions, stats, people, bulk export |
| Write sessions and action items | Update title, notes, summary, tags, favorite, action items |
| Delete sessions | Permanently delete a session |
| Search sessions | Semantic search across your library |
| Read transcripts | Full transcripts with speaker segments |
| Access media | Signed download URLs for audio and video |
| Read account | Account info and subscription status |
| Manage webhooks | Register and manage webhook endpoints |
| Read event feed | Pull and acknowledge the event feed |
| Read folders | List and open folders (Read sessions also works) |
| Manage folders | Create, rename, recolor, pin, reorder, and delete folders, and add or remove sessions |
| Share sessions and manage access | Share your sessions with other Wave users, see who has access, and remove people |
| Import recordings (uses your import allowance) | Import audio and video into Wave by link or upload. Never included in the write permission; tick it on its own |
Call an endpoint without the matching permission and you get a 403 naming what's missing.
Reading your data
GET /v1/sessions— newest first, cursor paginated, filterable bytype,since,folder,tag, andperson.foldertakes an id, a name, or aParent/Childpath, and a parent folder includes its sub-folders' sessions unless you passinclude_subfolders=false. Only sessions that finished processing are returned.GET /v1/sessions/:id— title, duration, markdown summary, notes, tags, favorite. Phone calls also carry direction and numbers.GET /v1/sessions/:id/transcript— a flat transcript string plus timed, speaker-labeled segments.GET /v1/sessions/:id/action-items— structured action items and a version number.GET /v1/sessions/:id/media— signed audio and video URLs, good for one hour.POST /v1/sessions/search— semantic search, up to 50 results, optional tag filters.POST /v1/sessions/bulk— up to 50 sessions in one call, with summaries and transcripts. The fast way to backfill.GET /v1/folders,GET /v1/folders/:id,GET /v1/sessions/stats— folders, and totals by type and platform. Folders nest one level deep: each folder has aparent_id(nullat the top level), andGET /v1/folders?parent_id=noneor?parent_id={id}lists one level.
People
People are the voices you saved as Voice IDs. They need only the Read Sessions permission, and they're read-only.
GET /v1/people— everyone you saved a voice for, with how many recordings each is in and when they were last heard. Your own voice is markedis_meand comes first.GET /v1/people/:id/sessions— one person's recordings, newest first, cursor paginated, filterable bytype,from, andto. Each row shows how long they spoke, the name they have in that transcript, and their three longest lines. Usemeas the id for your own voice.GET /v1/sessions?person=:id— the ordinary session list, narrowed to the recordings that person is in.
Voice samples are never returned, and neither are full transcripts; fetch a transcript separately when you need more than the three lines. If you merged two Voice IDs in Wave, the old id returns a 404 whose merged_into names the id to use. While Wave is still indexing an account's people, counts cover only the newest 1,000 recordings and responses carry partial: true.
Writing back
PATCH /v1/sessions/:id sets title, notes, summary (markdown), tags, favorite, and action items. For action items, read them first and pass back the version you got — a concurrent edit in the Wave app is then rejected instead of silently overwritten. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id, and the folder membership endpoints (POST and DELETE /v1/sessions/:id/folders/:folderId) organize sessions. Folders are non-exclusive, so a session can sit in several, and deleting a folder doesn't delete the sessions in it. Pass parent_id to POST /v1/folders to create a sub-folder, or to PATCH /v1/folders/:id to move a folder (null moves it back to the top level). The parent must be a top-level folder, and a folder that has sub-folders can't be moved inside another; either returns a 400 invalid_parent. Deleting a parent moves its sub-folders to the top level.
DELETE /v1/sessions/:id is permanent and not the same as deleting in the app. Treat it as unrecoverable.
Importing recordings
POST /v1/sessions/import creates a session from an audio or video file. Wave transcribes and summarizes it exactly like a file imported in the app. It needs the Import recordings (uses your import allowance) permission (sessions:import). Send one of:
source_url: a public https link to the file itself. Wave downloads it (up to 2 GiB) and answers202withstatus: "fetching".upload: with acontent_type(and optionallyfilenameandsize_bytes). Wave answers201with a signedupload.url. PUT the file there within 15 minutes with exactly theupload.headersit gives you (up to 5 GiB). Processing starts by itself when the upload finishes.
You can also pass title, notes, tags, language, and recorded_at. Then poll GET /v1/sessions/:id for processing_status, or listen for the Session completed webhook.
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"}'Send an Idempotency-Key header to make retries safe: repeating the same key and body returns the original session instead of a second import.
Supported formats: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG, and MPEG-TS. Imports share your account's import allowance with the Wave apps: 12 an hour and 20 a day (40 and 100 for paying customers; fewer for accounts less than two days old). Over that you get a 429 import_rate_limited, and a free plan with no minutes left gets a 403 subscription_required.
Sharing
A token acts as you, so it can read the sessions other Wave users shared with you with the permissions above. GET /v1/shared-sessions lists them, and GET /v1/shared-sessions/{owner_id}/{id} plus its /transcript, /action-items, and /media read one. Add include=shared to GET /v1/sessions to mix them into your own list; each row then carries access (owner or shared) and, for shared rows, the owner. Shared rows can't be filtered by folder or tag, shared sessions are read-only, and search covers only your own sessions.
With Share sessions and manage access, a token can share your own sessions: /v1/sessions/{id}/sharing shows who has access, and the routes under it create an invite link, email invites (up to 10 addresses per call), cancel a pending invite, remove one person, or reset the link. See Sharing Sessions from Claude, ChatGPT, the API and the CLI for the full list and the limits.
Rate limits
Every token gets 60 requests per minute and 10,000 requests per day. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, and a 429 includes Retry-After — back off rather than retrying straight away.
Repeating the same search query more than ten times an hour also returns a 429. Identical searches return identical results, so use webhooks or GET /v1/sessions?since= to find what's new.
Webhooks
Instead of polling, have Wave POST to you. In the Webhooks section click Add webhook, enter an Endpoint URL (HTTPS only, and URLs resolving to private addresses are rejected), pick your Events, and click Create webhook. The Signing secret is shown once — store it then. You can have up to five webhooks.
The events: Session completed (sent once, after processing finishes and the summary is queryable; the one most integrations want), Session updated, Action items updated (sent when action items are written or edited through the API), and Session deleted. You can also register a webhook from your own code with POST /v1/webhooks (or wave webhooks create).
Session completed can carry more than the summary. When you create a webhook with POST /v1/webhooks, or change one with PATCH /v1/webhooks/:id, pass an include object:
{ "include": { "summary": true, "transcript": true, "action_items": true } }summary is on by default; transcript and action_items are off. Including the transcript needs a token with Read transcripts. Very long transcripts are cut at 200,000 characters and marked transcript_truncated: true; fetch the rest from GET /v1/sessions/:id/transcript. Action items are the ones on the session when it completes; if Wave adds more a moment later, you get an Action items updated event. Other events always carry the plain session.
Each delivery is signed with your secret and arrives with X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp, and X-Wave-Webhook-Signature headers. Verify the signature before trusting a payload; the exact string to sign is in the API reference.
Wave doesn't guarantee one delivery per event. A delivery that times out (10 seconds) or returns a non-2xx is retried up to three times on a short backoff — about 10 seconds, then a minute, then five minutes — and the same event can legitimately arrive more than once. Make your handler idempotent: key on X-Wave-Webhook-Id, ignore an id you've already processed, and return a 2xx quickly. An endpoint that's down longer than that window drops the events it missed, so use the event feed below to catch up.
If an endpoint fails ten times in a row, Wave marks it Turned off automatically and stops sending. Fix the endpoint, then select Turn webhook back on on the webhook row.
No server? Use the event feed
If you can't host a public URL, poll instead. GET /v1/events returns events after a cursor Wave tracks per token, and POST /v1/events/ack advances it once you've processed them, so restarting a script doesn't replay everything. Pages default to 50 and cap at 200, and the feed carries action-item changes too. Needs the Read event feed permission.
The Wave CLI wraps this in wave events tail if you'd rather not write the polling loop.
FAQ
api.wave.co/reference has every endpoint, parameter, and response shape with live examples. api.wave.co/llms.txt is the same material as plain text — paste it into an AI assistant and have it write the integration for you.
Always JSON, with a code and a message. The common ones: 401 invalid_token (expired, revoked, or mistyped), 403 insufficient_scope (the token lacks a permission), and 429 (rate limited).
Only the ones people shared with you. A token is bound to the account that created it: it returns that account's sessions, plus sessions other Wave users shared with that account, read-only.
Was this article helpful?
Still need help?