API and MCP capability map

Which endpoint, MCP tool, CLI command and scope does each job: the hosted agent, the twelve tools, files, webhooks and workspace settings.

Updated 2026-10-22

Everything Wavemaker makes goes through one of two doors. The session API hands a brief to the hosted agent, which picks the method itself. The twelve tools let your own code or agent do the work step by step. The session API is reached over HTTP, the CLI and the SDKs; the tools are reached over all of those and MCP. Every surface applies the same validation, scopes, policies and result envelope.

Image, video, speech, music and editing are routes, model profiles and graphs behind these tools, not one endpoint per model. search finds them; read shows what each needs.

Choose a door

You want to	Use	Guide
Hand over a brief and get finished ads back	The session API, `/v1/sessions`	Make an ad
Drive each step yourself: one model, one edit, your own timeline or graph	The tools, `POST /v1/tools/{tool}`	Quote and run work
Let an outside agent such as Claude, ChatGPT, Cursor or Grok use Wavemaker	The same twelve tools over MCP at `https://api.wavemaker.io/mcp`	MCP setup
Work from a terminal	The `wavemaker` CLI	CLI

Task map

The MCP tool always has the same name and arguments as the HTTP tool, flattened, plus optional project and request_id. The CLI column lists the wavemaker command; wavemaker api call {tool} reaches any tool, and a tool that can spend also needs --request-id {id}. A dash means there is no dedicated command.

Make and price work with the hosted agent

Task	HTTP	CLI	Scope
Price a brief without a session	`POST /v1/quotes`	`wavemaker make "..." --quote-only`	any
Start a session and post a brief	`POST /v1/sessions`, then `POST /v1/sessions/{id}/turns`	`wavemaker make "..."`	`run`
Price a turn in a session	`POST /v1/sessions/{id}/turns` with `quote_only: true`	–	`run`
Follow a session's events	`GET /v1/sessions/{id}/events`	`wavemaker production watch {id}`	`read`
Read a turn's outcome and deliveries	`GET /v1/sessions/{id}/requests/{request_id}`	–	`read`
List sessions	`GET /v1/sessions`	`wavemaker production list`	`read`
Send a follow-up or revision	`POST /v1/sessions/{id}/turns`	`wavemaker production steer {id} "..."`	`run`
Accept or decline an approval	`POST /v1/sessions/{id}/approvals/{approval_id}`	`wavemaker production approve {id} {approval_id}`	`run`
Stop a running turn	`POST /v1/sessions/{id}/interrupt`	`wavemaker production interrupt {id}`	`run`
Close a session	`POST /v1/sessions/{id}/close`	–	`run`
Take over a session after a restart	`POST /v1/sessions/{id}/claim` with `takeover: true`	–	`run`

Find and read

Task	HTTP or MCP tool	CLI	Scope
Find models, routes, graphs, nodes, cards, styles, formats, fonts, worked examples and past work	`search`	`wavemaker api call search`	`read`
Read a file, artifact, job, card, graph, model, route or receipt	`read`	`wavemaker api call read`	`read`
See the credit balance	`read` of `wm://credits`	`wavemaker api call read`	`read`
List projects	`read` of `wm://file/`	`wavemaker api call read`	`read`
List a project's files	`read` of `wm://file/{project}/`	`wavemaker api call read`	`read`
Search the web	`generate` with route `firecrawl.search` (`firecrawl.scrape` for one page)	`wavemaker api call generate`	`run`

Make media yourself

Task	HTTP or MCP tool	CLI	Scope
Price a `generate`, `edit`, `compose` or `run` call	that tool with `quote_only: true`	`wavemaker api call {tool}`	`run`
Run a partner model route or a model profile	`generate` with `route` or `model`	`wavemaker api call generate`	`run`
Run a Comfy graph	`generate` with `graph`	`wavemaker run {graph} --request-id {id}`	`run`
Check a graph without running it	`generate` with `graph` and `validate_only: true`	`wavemaker graph validate {graph}`	`run`
Trim, crop, resize, reframe, fit an ad size, cut a 360 view, upscale, retime, grade, mix, extract audio, prepare a logo	`edit`	`wavemaker api call edit`	`run`
Render a timeline at draft or final tier, or package an HTML5 banner	`compose`	`wavemaker api call compose`	`run`
Run Python with the SDK, Pillow and fonts in a sandbox	`run`	`wavemaker api call run`	`run`
Wait on a job	`read` of `wm://job/{id}` with `wait_s`	`wavemaker watch {id}`	`read`
Cancel a job	`write` with `{uri: "wm://job/{id}", cancel: true}`	`wavemaker cancel {id}`	`write`
Collect a job's outputs	`read` of each `wm://artifact/{sha256}`	`wavemaker outputs {id} --out {dir}`	`read`

Check and deliver

Task	HTTP or MCP tool	CLI	Scope
Filmstrip, cuts, motion, on-screen text, faces, identity against plates	`watch`	`wavemaker api call watch`	`read`
Loudness, transcript against expected text, mix balance, voice auditions	`listen`	`wavemaker api call listen`	`run`
Score takes against plates, references or each other	`compare`	`wavemaker api call compare`	`run`
Critique a still, display set, video or audio against the brief and destination	`review`	`wavemaker api call review`	`run`
Check a file against a destination's spec and record the delivery	`deliver`	`wavemaker api call deliver`	`write`

Move files

Task	HTTP or MCP tool	CLI	Scope
Upload a file	`write` with `upload`, PUT, then `write` with `commit`; or `POST /api/v1/inputs`	`wavemaker files upload {path}`	`write`
Import a file from a public URL	`write` with `from_url`	`wavemaker api call write`	`write`
Write project files and memory	`write` to `wm://file/{project}/{path}` or `wm://memory/{path}`	`wavemaker api call write`	`write`
Download a file with the credential	`GET /api/v1/files/artifact/{sha256}`	`wavemaker files download artifact {sha256} --out {path}`	`read`
Get a signed download link	`read` of `wm://artifact/{sha256}`	`wavemaker api call read`	`read`
Copy files to your own S3-compatible bucket	`/v1/destinations`, `POST /v1/exports`	–	`write` (listing `read`)

Account and workspace

Task	HTTP	CLI	Scope
See who a credential is	`GET /v1/identity`	`wavemaker auth status` shows the saved sign-in	any
List the tools and their schemas	`GET /v1/tools`	`wavemaker api list` lists the tool names without connecting	any
Push events to your server	`/v1/webhooks/endpoints`, `/v1/webhooks/deliveries`	–	`write` (reads `read`)
Read or set the model and route policy	`GET`, `PUT /v1/workspace/policy`	–	`read`; `write` and owner or admin to set
Account, credits, content, support and other older operations still served	`POST /api/v1/ops/{name}`	`wavemaker api call {operation}`	the operation's

"Any" means any live credential. See Account API access for the older operations that remain.

The twelve tools

Tool	What it does	Scope
`search`	Find tools, cards, graphs, models, routes, nodes, worked examples, past work, fonts, formats, styles and recipes. Never spends.	`read`
`read`	Read a file, folder, artifact (with a signed link), job, card, tool, graph, model, route, recipe, node, format, font, receipt or the balance; wait on jobs.	`read`
`write`	Write or delete files and memory, upload or import media, cancel a job.	`write`
`generate`	Run a route, a model profile or a Comfy graph; quote or validate first.	`run`
`edit`	Change one owned file into a new one; a still stays a still and audio stays audio.	`run`
`compose`	Render a timeline at draft or final tier, or package an HTML5 banner.	`run`
`watch`	Look at video: filmstrips, motion, cuts, on-screen text, faces and drift.	`read`
`listen`	Hear audio: loudness, silences, transcript, balance and voice auditions.	`run`
`compare`	Compare takes or candidates for identity, look, motion or text.	`run`
`review`	Measure and critique a still, display set, video or audio. Advisory.	`run`
`deliver`	Check final files against a destination's spec and record the delivery.	`write`
`run`	Python in a sandbox with the SDK, Pillow and fonts, for batches and pixel work.	`run`

generate, edit, compose, listen, compare, review and run can spend credits and need a request_id. generate, edit, compose and run also take quote_only: true to price a call first; listen, compare and review report what their model call cost in cost. MCP hosts see search, read, watch, listen, compare and review marked as read-only, because they change no project, file or delivery; listen, compare and review still charge credits.

Resources

Tools address resources by URI:

wm://file/{project}/{path}, and wm://file/ for the list of projects
wm://artifact/{sha256}
wm://memory/{path}
wm://job/{id} and wm://receipt/{id}
wm://card/{id}, wm://tool/{name}, wm://graph/{id}, wm://model/{id}, wm://route/{name}, wm://recipe/{name}, wm://node/{class}, wm://format/{id}, wm://font/{family}
wm://credits

Deliberate boundaries

Sign-in, OAuth consent, credential creation, provider-key entry, passwords and legal agreements stay in the browser. Never put a password or provider key in a tool argument.
Generating doesn't publish anything. Only deliver with a delivery_* role marks a file delivered, and Wavemaker doesn't buy media or launch campaigns.
review is advisory. Delivery checks a destination's spec; it doesn't judge quality.
A session can't switch to another agent mid-conversation. To use your own agent, give it the tools over MCP, the CLI or an SDK.
The older agents.*, productions.*, jobs.*, compute.*, creative.*, generation.*, capabilities.* and api.* operations are not served (501 operation_not_ported).