Build on Wave

Quickstart

API keys and authentication

Wave API tokens are prefixed wave_api_ and MCP tokens wave_mcp_. Both are minted by the account owner at app.wave.co/settings/integrations. Only a SHA-256 hash is stored, so the plaintext value appears exactly once — copy it then. Send it as a bearer credential:

Scopes

Tokens carry only the scopes you grant them. A token that will never write should not hold a write scope.

sessions:read

List and read session metadata, summaries, and action items.

sessions:write

Update session titles, notes, tags, and structured action items.

sessions:delete

Delete a session and its recording.

sessions:search

Run semantic search across the account's sessions.

transcripts:read

Read full transcripts with speaker segments.

media:read

Mint signed URLs for session audio and video.

account:read

Read the token owner's profile and subscription state.

folders:read

List and read folders.

folders:write

Create, rename, recolour and delete folders and manage session membership.

events:read

Poll the per-token event cursor feed and acknowledge events.

webhooks:manage

Register webhook endpoints, rotate secrets, and send test deliveries.

sharing:manage

Share sessions with other Wave users and manage who has access.

The same vocabulary is machine-readable as scopes_supported in RFC 9728 protected-resource metadata at api.wave.co/.well-known/oauth-protected-resource. A 401 or 403 from the API names that URL in its WWW-Authenticate challenge — with scope="..." on a 403, so a client knows exactly which grant its next token needs.

OAuth 2.0

The MCP surface authenticates with OAuth 2.0 — authorization code with PKCE and dynamic client registration, with RFC 8414 server metadata at mcp.wave.co/.well-known/oauth-authorization-server (wave.co's own well-known path 307s there). The REST API deliberately does not use OAuth: wave_api_ tokens are minted by the account owner and sent as plain Bearer credentials, so there is no authorization flow to run against api.wave.co.

OpenAPI specification

The full API surface is published as OpenAPI 3.1 at wave.co/openapi.json. Every operation carries a unique operationId, a description, typed parameters, and response schemas, so it loads directly into an LLM function-calling toolchain or a client generator without hand-editing.

MCP server

mcp.wave.co speaks the Model Context Protocol over Streamable HTTP, supporting protocol versions 2025-11-25, 2025-06-18, 2025-03-26. Authorization is OAuth 2.0 with PKCE, or a manually minted wave_mcp_ token for clients that cannot run the OAuth flow. Connection details are discoverable at wave.co/.well-known/mcp.

No account yet? Start with the documentation server

A second, public MCP server at wave.co/mcp needs no authentication at all. It exposes this documentation — the developer portal, the versioning policy, and the full OpenAPI specification — as MCP resources, with search_docs and read_doc tools, so an agent can read the integration docs before anyone signs up. It holds no user data.

Read tools (10)

search_sessions

Search across your Wave sessions using semantic search.

list_sessions

List your recent Wave sessions.

list_folders

List the user's folders.

get_session

Get full details for a specific Wave session, including the summary and optionally the transcript.

get_transcript

Get the transcript for a Wave session with speaker attribution.

get_action_items

Read the structured action items attached to a Wave session, plus the current version.

search

Search the user's Wave sessions (meetings, calls, recordings) by meaning.

fetch

Fetch the full content of a Wave session by id: summary plus speaker-labeled transcript, with metadata.

list_shared_sessions

List sessions other Wave users have shared with the user, newest share first.

list_session_access

For one of the user's own sessions, list the people who have access (recipient_id, name, email, shared_at, how they got it) and the emailed invites nobody has accepted yet.

Write tools (8)

update_action_items

Write back the structured action items for a Wave session.

create_folder

Create a folder for organizing sessions.

add_session_to_folder

Add a session to a folder.

remove_session_from_folder

Remove a session from a folder.

update_folder

Rename, recolour, pin, reorder, or change the session sort of a folder.

delete_folder

Delete a folder.

share_session

Share one of the user's own sessions with other people.

unshare_session

Remove access to one of the user's own sessions.

Write boundary

• Cannot delete sessions, recordings, or transcripts
• Cannot edit recording media or transcript text
• Reads the authenticated Wave user's own sessions plus sessions other people shared with them; shared sessions are read-only
• Writes only to the user's own data; sharing a session gives the people named read access, never edit access
• All tools are closed-world (openWorldHint: false)

Command-line client

The Wave CLI is published on npm as @waveai/cli. It installs a wave binary, which means an agent with shell access can read Wave sessions without anyone writing an HTTP client first.

Command reference: api.wave.co/cli.

Sharing

A token acts as the person who minted it, so it can do what they can do with sharing in the app. Read sessions other Wave users shared with you at GET /v1/shared-sessions, or add include=shared to GET /v1/sessions. For your own sessions, create a link, email invites, see who has access, and remove people under /v1/sessions/{id}/sharing with the sharing:manage scope. Over MCP the same work is list_shared_sessions, share_session, list_session_access, and unshare_session; in the CLI it is wave shared and wave sessions share. Shared sessions are read-only, and search covers only your own sessions.

Webhooks and events

Register an endpoint through the API to receive session events, rotate its signing secret, and send test deliveries. If you would rather not host a receiver, GET /v1/events is a per-token cursor feed carrying the same event shapes — poll it and acknowledge with POST /v1/events/ack. Both are described in the OpenAPI spec.

Rate limits

Responses carry rate-limit headers so a client can pace itself without discovering the limit by hitting it. The endpoints on wave.co send the fields below, which follow draft-ietf-httpapi-ratelimit-headers; the older X-RateLimit-* spelling is sent alongside for clients that already read it. Both wave.co and api.wave.co send both spellings — api.wave.co on every /v1 response, including the 401 an unauthenticated request gets, so you can observe the fields before you have a token: curl -si https://api.wave.co/v1/sessions.

RateLimit-Policy: "daily";q=5;w=86400

The quota (q) and its window in seconds (w).

RateLimit: "daily";r=3;t=41213

Requests remaining (r) and seconds until reset (t).

Retry-After: 41213

Seconds to wait, sent on a 429.

• Free transcription tool (wave.co) — 5 files per day, per browser, resetting at 00:00 UTC
• Developer API (api.wave.co) — 60 requests per minute and 10,000 per day, per token — standard RateLimit fields plus the legacy X-RateLimit-* spelling on every response, including the 401 an unauthenticated request gets
• Documentation MCP server (wave.co/mcp) — 240 requests per 60 seconds, per IP address, no authentication

Versioning and deprecation

Every endpoint is versioned in the URL path. A breaking change ships as a new version prefix; the previous version keeps working while it is deprecated. The current version is v1, at api.wave.co/v1.

Safe to expect inside a version

• New endpoints, new optional request parameters, new response fields
• New enum values in fields documented as extensible
• Relaxed validation, or a new optional authentication scope

Only ever in a new version

• Removing or renaming an endpoint, field, or enum value
• Making an optional parameter required, or narrowing accepted values
• Changing the type or meaning of an existing response field

How a deprecation is signalled

A deprecated endpoint keeps working and starts announcing itself in its own responses. Watch for these; do not rely on reading this page.

Deprecation: @1735689599

Structured-field date at which the endpoint became (or becomes) deprecated. (RFC 9745)

Sunset: Wed, 31 Dec 2025 23:59:59 GMT

HTTP-date after which the endpoint may stop responding. (RFC 8594)

Link: <https://wave.co/developers>; rel="deprecation"; type="text/html"

Points at the note explaining the change and its migration. (RFC 9745)

No Wave API endpoint is currently deprecated. The complete policy — including what is and is not committed — lives at wave.co/developers/versioning.

Getting started without talking to anyone

Free tier — available

Wave's free plan includes 30 minutes of recording per month, with transcription, summaries, and API access. No credit card. wave.co/pricing

Self-serve API keys — available

API and MCP tokens are minted by the account owner in Wave settings, with per-token scopes. No sales conversation, no approval step. app.wave.co/settings/integrations

Documentation over MCP, no account — available

The documentation MCP server at wave.co/mcp needs no account, no token, and no OAuth. Connect to it to read the developer portal, the versioning policy, and the full OpenAPI specification as MCP resources before writing any code. wave.co/mcp

Sandbox environment — not available

There is no separate sandbox environment. Test against a free account: it exercises the same endpoints and the same data model as a paid one, on that account's own sessions. wave.co/pricing

All developer resources

Wave Developer API API

REST API over sessions, transcripts, summaries, action items, folders, sharing, and webhooks. Bearer auth, cursor pagination, stable response shapes.

Wave OpenAPI Specification Spec

OpenAPI 3.1 description of every Wave API endpoint, with a unique operationId, typed parameters, and response schemas on each operation — ready to load into an LLM function-calling toolchain.

Wave API Reference API

Browsable endpoint reference with request and response examples for the Wave Developer API.

Wave MCP Server MCP

Hosted Model Context Protocol server over Streamable HTTP. 18 tools (10 read, 8 write) for Claude, ChatGPT, Claude Code, Codex, Cursor, Grok, Muse, and any MCP client.

Wave Documentation MCP Server MCP

Public Model Context Protocol server over Streamable HTTP, no account required. Exposes Wave's developer documentation and OpenAPI specification as MCP resources, plus read-only search and fetch tools, so an agent can read the integration docs before anyone signs up.

Wave MCP Setup Guide MCP

Per-client connection instructions for the Wave MCP server, including OAuth and manual wave_mcp_ tokens.

Wave CLI CLI

Official command-line client, published on npm as @waveai/cli. Installs the `wave` binary for scripting Wave from a terminal or an agent shell.

Wave API Authentication Auth

Mint, scope, and revoke wave_api_ and wave_mcp_ tokens. Tokens are stored as SHA-256 hashes and shown in plaintext exactly once. The scope vocabulary is machine-readable in RFC 9728 metadata at api.wave.co/.well-known/oauth-protected-resource.

Wave Webhooks Webhooks

Register endpoints for session events, rotate signing secrets, and send test deliveries. A polling alternative exists at /v1/events for receivers you would rather not host.

Help

Developer and API questions go to support@wave.co. Include the request id from the response header when reporting a problem with a specific call. Every other channel is listed on the contact page, and the product story behind these surfaces is on Wave for Agents.