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 19, 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. For copy-paste MCP client configs (Cursor, Claude, Windsurf, VS Code) and lean/compact/full tool-registration modes, see /developers#mcp.

Authentication

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

curl https://api.wavemaker.io/api/v1/videos \
  -H "Authorization: Bearer mcp_your_key_here"

Keys are user-scoped or org-scoped (tenancy follows the key). Org-scoped keys bill the organization’s credits; user-scoped keys bill that user. Catalog Video mutating routes also require the key be attached to both an organization and a user.

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
{ "composition_id": "…", "quality": "hd" }   # omitted → lowest plan tier; preview|sd|hd|4k — same engine as dashboard Export (plan gate + credits + Modal SR when engaged); hd = 1080 short side
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 (MCP: get_account / get_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.
  • Static ads / plain images: POST /api/v1/static-ads (+ GET /api/v1/image-styles / list_image_styles; ad-styles / list_ad_styles are deprecated aliases).
  • Catalog Video adds its own machine surfaces — the campaign manifest API and dco.variant.updated webhooks (details).

Catalog Video (DCO) API + MCP

Catalog Video is a first-class product lane (feed → per-SKU video or still → delivery → freshness). Full REST table: public API reference / docs/public-api.md. Operational invariants: docs/catalog-video.md (§ Static Image DCO for Catalog Stills).

# Create a scrape source + campaign, plan, produce a sample
POST /api/v1/dco/sources
{ "name": "My shop", "kind": "product", "source": "scrape", "source_ref": "https://…" }

# Video (default)
POST /api/v1/dco/campaigns
{ "name": "Summer videos", "source_ids": ["dsrc_…"], "output_medium": "video" }

# Catalog Stills (requires dcoStaticImageEnabled)
POST /api/v1/dco/campaigns
{ "name": "Summer stills", "source_ids": ["dsrc_…"], "output_medium": "image", "feed_image_policy": "ads_branded" }

POST /api/v1/dco/campaigns/{id}/plan
POST /api/v1/dco/campaigns/{id}/produce
  -H "Idempotency-Key: …"
{ "sample_only": 3 }

GET  /api/v1/dco/campaigns/{id}/manifest
GET  /api/v1/dco/campaigns/{id}/activation-kit?platform=google

MCP tools mirror the same service layer — prefer composites dco_bootstrap_catalog (pass output_medium + feed_image_policy for Stills), dco_run_produce, dco_get_status_bundle, dco_review_variants, dco_manage_delivery. Dashboard: /campaigns. Kill switches: dcoEnabled and dcoStaticImageEnabled at /admin#flags.

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, brand kits, 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. Managed + workspace tools accept webhook_url + webhook_secret (signed) for the same events as REST; see the Webhooks section on /developers.
  • Compact mode: if a client can’t load ~90 dynamic tools, operators can set CONFIG KV workspace_mcp:compact=true so agents use describe_tool + execute_tool instead (fail-safe default = full catalog).

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.