@waveai/sdk

TypeScript client for the Wave AI Developer API (https://api.wave.co). Read sessions, transcripts and summaries, search, import recordings, organise folders, share sessions, and manage webhooks.

Works anywhere with a global fetch: Node 18+, Bun, Deno, browsers and edge runtimes. ESM and CommonJS builds with type declarations. No dependencies.

npm install @waveai/sdk

Authentication

Create a token at app.wave.co/settings/integrations/api and pick only the scopes you need. Keep it on the server.

import { WaveClient } from '@waveai/sdk';

const wave = new WaveClient({ apiKey: process.env.WAVE_API_KEY! });

Read

const { sessions, next_cursor } = await wave.listSessions({ limit: 20 });
const session = await wave.getSession(sessions[0].id);          // sessions:read
const { transcript } = await wave.getTranscript(session.id);     // transcripts:read
const results = await wave.searchSessions('pricing decision', { limit: 10 }); // sessions:search

Import a recording (scope sessions:import)

From a public https URL (Wave downloads it, up to 2 GiB):

const created = await wave.importFromUrl('https://example.com/standup.mp3', {
  title: 'Daily standup',
  idempotencyKey: 'standup-2026-10-21', // safe to retry
});
const ready = await wave.waitForSession(created.id); // or listen for session.completed
console.log(ready.summary);

Upload a file yourself (up to 5 GiB). Processing starts when the upload finishes:

import { readFile } from 'node:fs/promises';

const bytes = await readFile('lecture.m4a');
const session = await wave.importFile(bytes, { content_type: 'audio/mp4', filename: 'lecture.m4a' });

Or in two steps, for example to hand the signed URL to a browser:

const { id, upload } = await wave.createImportUpload({ content_type: 'audio/mpeg' });
// PUT the file to upload.url with exactly upload.headers, within 15 minutes.
await wave.uploadImportFile(upload, fileBlob);

Formats: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG and MPEG-TS. Imports share the account's import limits with the Wave apps (12 per hour, 20 per day; more for paying customers). Over the limit you get a WaveAPIError with code: 'import_rate_limited' (429); a free plan out of minutes gets subscription_required (403).

Write back

await wave.updateSession(id, { title: 'Q4 planning', notes: 'Follow up with legal', tags: ['planning'] }); // sessions:write
await wave.updateSession(id, { summary: '## Decisions\n- Ship on Friday' });

const { action_items, version } = await wave.getActionItems(id);
await wave.updateActionItems(id, [...action_items, { text: 'Send the deck', due_date: 'Friday' }], { ifMatch: version });

Webhooks (scope webhooks:manage)

const hook = await wave.createWebhook('https://example.com/wave', ['session.completed'], {
  include: { transcript: true, action_items: true }, // transcript needs transcripts:read
});
console.log(hook.secret); // shown once; verify X-Wave-Webhook-Signature with it

Errors

Every non-2xx response throws WaveAPIError with status, code and message:

import { WaveAPIError } from '@waveai/sdk';

try {
  await wave.getSession('nope');
} catch (err) {
  if (err instanceof WaveAPIError && err.status === 404) { /* not found */ }
}

Reference

• API reference: https://api.wave.co/reference
• OpenAPI: https://api.wave.co/v1/openapi.json
• Agent-friendly docs: https://api.wave.co/llms.txt
• MCP server for Claude, ChatGPT and Cursor: https://mcp.wave.co

Copyright Mohrer Associates LLC. Licence terms: see package.json.