Wave Developer API
Create a scoped token and read or update your Wave sessions, transcripts, and action items from your own code — with search, bulk export, and webhooks.
The Wave 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, update titles 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, open your profile, pick the Integrations tab, and open Developer API — 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. 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, when it was created, and when it was last used. The trash icon opens Revoke Token — revocation takes effect immediately, and anything using that token starts getting a 401.
API tokens expire one year after they're created, and the expiry isn't shown in the token list. If an integration that ran fine for months suddenly returns 401 invalid_token, 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, folders, bulk export |
| Search Sessions | Semantic search across your library |
| Read Transcripts | Full transcripts with speaker segments |
| Access Media | Signed download URLs for audio and video |
| Write Sessions & Action Items | Update title, notes, tags, favorite, action items |
| Delete Sessions | Permanently delete a session |
| Manage Folders | Create folders, add and remove sessions |
| Manage Webhooks | Register and manage webhook endpoints |
| Read Event Feed | Pull and acknowledge the event feed |
| Read Account | Account info and subscription status |
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, andtag. 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/sessions/stats— folders, and totals by type and platform.
Writing back
PATCH /v1/sessions/:id sets title, notes, 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 and the folder membership endpoints organize sessions; folders are non-exclusive, so a session can sit in several.
DELETE /v1/sessions/:id is permanent and not the same as deleting in the app. Treat it as unrecoverable.
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.
Three events register today: Session Completed (fires once, after processing finishes and the summary is queryable — the one most integrations want), Session Updated, and Session Deleted.
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 Auto-disabled and stops sending. Fix the endpoint, then use the re-enable button 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 also carries action-item changes that webhook subscriptions don't. 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).
No. A token is bound to the account that created it and only ever returns that account's sessions.
Was this article helpful?
Still need help?