Build on the conversations that move work forward.

Start here

Make your first request in minutes.

Create a scoped token, send it as a Bearer credential, and get back predictable JSON.

curl -H "Authorization: Bearer wave_api_xxx..." \
  https://api.wave.co/v1/sessions

{
  "sessions": [
    {
      "id": "abc123",
      "title": "Weekly Standup",
      "timestamp": "2025-01-20T10:00:00Z",
      "duration_seconds": 1800,
      "type": "meeting",
      "platform": "zoom"
    }
  ],
  "next_cursor": "2025-01-19T09:00:00Z",
  "has_more": true
}

Access control

Authentication

All API requests must be authenticated using a Bearer token in the Authorization header.

Creating a Token

1. Go to app.wave.co/settings/integrations/api
2. Click "Create Token" and give it a descriptive name
3. Select the permissions (scopes) your application needs
4. Copy the token immediately — it will only be shown once

Scopes

Tokens are granted specific permissions that control what data they can access. Request only the scopes your application actually needs.

Token Security

• Tokens are only shown once when created — store them securely
• Tokens expire after 1 year but can be revoked at any time
• Use environment variables to store tokens, never commit them to code
• Create separate tokens for different applications
• Revoke tokens immediately if they may have been compromised
• Grant only the scopes your application needs (principle of least privilege)

Error Responses

Authentication errors return appropriate HTTP status codes:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "Token is invalid, expired, or revoked"
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'sessions:write' scope"
  }
}

Build surface

API Endpoints

Quick reference for all Wave API endpoints. For request/response schemas and a built-in request builder, see the Interactive API Reference.

All endpoints require a Bearer token. Base URL: https://api.wave.co

Sessions

Folders

Folders are non-exclusive — a session can live in many folders at once. Pair GET /v1/folders with GET /v1/sessions?folder=… to scope results, or use the membership endpoints to organize sessions programmatically.

Event Feed

Stripe-style per-token cursor. Wave keeps track of where you are in the event stream on the server, so you don't have to maintain dedupe state on the client. Use instead of — or alongside — webhooks. Same event shapes, same ids.

Transcripts

Media

Account

Sharing

Read sessions shared with you through REST or MCP. Shared sessions are read-only; each grant determines access to summaries, transcripts, audio, and action items. Keep both the owner ID and session ID.

All owner operations require sharing:manage. Links expire after 30 days and are claimed in the app. Revoked recipient access returns 404. Callable rate limits return 429 sharing_rate_limited; temporary failures return 503 sharing_unavailable.

Search and the regular sessions list cover your own sessions only. Shared sessions cannot be filtered by folder or tag. Shared action items omit edit provenance and use version 0 / updated_at null because they are read-only. Sharing events/webhooks, Teams sources, and setting per-invite scopes are deferred; scope is read-only.

Reactive workflows

Webhooks

Register HTTPS endpoints to receive real-time notifications when sessions are completed, updated, or deleted. Payloads are signed with HMAC-SHA256 for verification.

Webhook Events

Signature Verification

Each delivery includes these headers for verification:

To verify: compute HMAC-SHA256(secret, "webhookId.timestamp.body") and compare with the signature header.

Predictable failures

Error Codes

All errors return a consistent JSON structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Usage guardrails

Rate Limits

• 60 requests per minute per token
• 10,000 requests per day per token

Rate limit info is included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706000000

Machine-readable contract

API Reference

The full OpenAPI 3.1 specification is available at:

Use it to generate client libraries, import into Postman, or validate requests.