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:write

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

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 (8)

search_sessions

Semantic search across the authenticated user's sessions. Returns ranked sessions with snippets and metadata.

list_sessions

Browse recent sessions with cursor pagination, filterable by type, date, folder, and tag.

list_folders

List folder ids, names, colors, and session counts for scoping other calls.

get_session

Get one session's title, summary, metadata, notes, tags, action items, and optionally its full transcript.

get_transcript

Get a session transcript as segments, plain text, or speaker-labeled text.

get_action_items

Get a session's structured action items plus the current version for safe round-trip edits.

search

Compatibility search for ChatGPT deep research and company knowledge. Returns citable id, title, and URL.

fetch

Compatibility fetch for an id returned by search. Returns summary, speaker-labeled transcript, and metadata.

Write tools (4)

update_action_items

Replace a session's action-item list, with an optional expected_version check that rejects overwrites of a concurrent user edit.

create_folder

Create a folder by name, with an optional color. Idempotent — returns the existing folder if the name is taken.

add_session_to_folder

Add a non-exclusive folder membership. A session can belong to several folders.

remove_session_from_folder

Remove one folder membership. The session, recording, and transcript are untouched.

Write boundary

• Cannot delete sessions, recordings, or transcripts
• Cannot edit recording media or transcript text
• Reads and writes only data owned by the authenticated Wave user
• 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.

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. The Developer API on api.wave.co currently sends the legacy spelling only — read X-RateLimit-Remaining there. To see the standard fields on a live response without authenticating, hit the public documentation MCP server: curl -si -X POST https://wave.co/mcp returns them on every reply.

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 (legacy X-RateLimit-* headers only)
• 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, 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. 12 tools — 8 read, 4 write — for Claude, ChatGPT, Claude Code, and Cursor.

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.

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.