Help Center

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

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

PermissionWhat it allows
Read sessionsList and open sessions, stats, people, bulk export
Write sessions and action itemsUpdate title, notes, summary, tags, favorite, action items
Delete sessionsPermanently delete a session
Search sessionsSemantic search across your library
Read transcriptsFull transcripts with speaker segments
Access mediaSigned download URLs for audio and video
Read accountAccount info and subscription status
Manage webhooksRegister and manage webhook endpoints
Read event feedPull and acknowledge the event feed
Read foldersList and open folders (Read sessions also works)
Manage foldersCreate, rename, recolor, pin, reorder, and delete folders, and add or remove sessions
Share sessions and manage accessShare 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 by type, since, folder, tag, and person. folder takes an id, a name, or a Parent/Child path, and a parent folder includes its sub-folders' sessions unless you pass include_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 a parent_id (null at the top level), and GET /v1/folders?parent_id=none or ?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 marked is_me and comes first.
  • GET /v1/people/:id/sessions — one person's recordings, newest first, cursor paginated, filterable by type, from, and to. Each row shows how long they spoke, the name they have in that transcript, and their three longest lines. Use me as 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 answers 202 with status: "fetching".
  • upload: with a content_type (and optionally filename and size_bytes). Wave answers 201 with a signed upload.url. PUT the file there within 15 minutes with exactly the upload.headers it 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

Was this article helpful?

Still need help?

Email support

On this page