API & MCP

Use Wavemaker programmatically — the REST API for generation, status, and tools, and the MCP server for AI agents like Claude and Cursor.

Last updated July 3, 2026

Everything Wavemaker does in the app is available programmatically. There are two surfaces: a REST API for your backend and scripts, and an MCP server so AI agents can drive video production directly.

The complete endpoint-by-endpoint reference lives at /developers. This page is the map.

Authentication

Create an API key in Dashboard → API Keys and send it as a bearer token:

curl https://api.wavemakr.com/api/v1/videos \
  -H "Authorization: Bearer mcp_your_key_here"

Keys are org-scoped — usage bills the org’s credits.

The core flow

# 1. Start a generation
POST /api/v1/videos
{ "prompt": "A 30-second ad for https://yourbrand.com, energetic, 9:16" }
# → { "job_id": "wf_..." }

# 2. Poll status — or stream progress over SSE
GET /api/v1/videos/{job_id}
GET /api/v1/videos/{job_id}/events        # real-time server-sent events

# 3. Fetch the finished composition, then render an MP4
GET  /api/v1/videos/{job_id}/composition
POST /api/v1/renders
GET  /api/v1/renders/{render_id}

# Cancel any time — unused credits are settled back
POST /api/v1/videos/{job_id}/cancel

Generation options mirror the composer: aspect ratio, duration, style (skill_type), model overrides, and attached assets (upload first via POST /api/v1/uploads, then reference the returned keys). A POST /api/v1/cost-estimates endpoint quotes a request before you commit, and GET /api/v1/account / GET /api/v1/usage report balance and itemized spend.

Refinement over the API

A finished composition accepts refinement instructions — the same natural-language edits as chat:

POST /api/v1/videos/{composition_id}/refine
{ "instruction": "Tighten scene 3 and change the CTA to 'Order today'" }

Standalone tools

Some capabilities run as one-shot tool runs — dispatch, poll, webhook — without a full generation:

POST /api/v1/workspaces/{workspace_id}/tools/upscale_video
GET  /api/v1/tool-runs/{run_id}
  • upscale_video — super-resolve any external video (details).
  • Discovery: GET /api/v1/tools lists every tool your key can run, with schemas.
  • Catalog Video adds its own machine surfaces — the campaign manifest API and dco.variant.updated webhooks (details).

Webhooks

Pass a webhook_url (and webhook_secret) when dispatching a generation or tool run to receive signed lifecycle events instead of polling. Verify the signature with your secret (scheme documented at /developers).

The MCP server

Wavemaker ships a hosted Model Context Protocol server, so agents (Claude, Cursor, or anything MCP-capable) can create and edit videos as tools:

  • Connect via OAuth — point your client at the MCP URL and a browser sign-in opens on first use (no pre-shared key needed). The tool surface mirrors the API (generate, status, refine, render, upscale, subjects/characters, styles and motion discovery, cancellation).
  • Sessions created over MCP are normal sessions — open them in chat or Canvas anytime.
  • The dynamic tool catalog is the same one GET /api/v1/tools returns, so an agent always sees your key’s current capabilities.

Setup instructions and the connection URL are at /developers#mcp.

Rate limits & good citizenship

Concurrency is limited per organization; long-running work should use webhooks over tight polling. Heavy media operations are queued fairly — a burst of requests never fails, it queues.