HTTP API

Call the hosted API with a bearer key: the session API, the twelve tools, quotes, identity and file transfer.

Updated 2026-10-21

Origins

Production: https://api.wavemaker.io
Staging: https://api-staging.wavemaker.io

Paths answer directly, with no redirects. GET /health answers {"ok": true, "service": "wmcore"} without a credential.

Authenticate

Send Authorization: Bearer {key} on every call. Create a workspace key under Connections → Developer setup, or let an MCP host sign in with OAuth. The key fixes the workspace; every read and write is scoped to it. Keep keys in private server configuration, never in a URL, a graph or browser code. GET /v1/identity shows what a key is: workspace, scopes, mode (live or test) and expiry. Credentials.

Writes from a browser page on another site are refused with origin_rejected (403). JSON bodies over 2 MB are refused with body_limit (413).

The API

Path	What it does
`POST /v1/sessions`, `GET /v1/sessions`, `/v1/sessions/{id}/**`	The hosted agent: create a session, post turns with a brief and deliverables, follow events, decide approvals, interrupt, close. Make an ad.
`POST /v1/quotes`	Price a turn without a session. Starts and holds nothing.
`GET /v1/identity`	The calling credential's workspace, scopes and mode.
`GET /v1/tools`, `POST /v1/tools/{tool}`	The twelve tools: `search`, `read`, `write`, `generate`, `edit`, `compose`, `watch`, `listen`, `compare`, `review`, `deliver`, `run`. Capability map.
`GET /api/v1/files/artifact/{sha256}`	Download an owned artifact with the key. Supports `Range`; sends `X-Content-SHA256`.
`GET /v1/downloads/{sha256}/{token}`	A signed download link (from `read` or a delivery). Needs no credential; valid for at most an hour.
`POST /api/v1/inputs`	Upload one file as raw bytes (`Content-Length`, `X-Content-SHA256`, `X-Filename`).
`/v1/webhooks/endpoints/`, `/v1/webhooks/deliveries/`	Signed event webhooks for the workspace.
`GET`, `PUT /v1/workspace/policy`	The workspace's model and route policy (owners and admins).

Tool calls

POST /v1/tools/{tool} takes {"args": {...}, "project": "{id}", "request_id": "{key}"}. request_id is required on any call that can spend (generate, edit, compose, listen, compare, review, run), except with quote_only or validate_only. A replay with the same key returns the original result. project can be omitted when the credential is scoped to one project.

curl --fail-with-body \
  --header "Authorization: Bearer $WAVEMAKER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"args":{"query":"vertical video ad","kinds":["card","format"],"limit":5}}' \
  https://api.wavemaker.io/v1/tools/search

Long work returns a job at once. Follow it with read of wm://job/{id} and wait_s (at most 25) until state is succeeded, failed or cancelled. Never resubmit to check progress. Quote and run work.

Results and failures

Every /v1 reply is the envelope {ok, data, error, job, cost, hints}. On failure data is null and error is {code, message, retryable, retry_after_s?, details?}; the HTTP status follows the code. Branch on error.code and error.retryable, never on the message, and ignore response fields you don't know. Infrastructure failures can be non-JSON, so check the HTTP status too. Errors and retries.

Older operations

POST /api/v1/ops/{name} serves a subset of the older operation catalog, in the older wmlab.result/1 envelope ({schema, ok, data, error}). GET /api/v1/operations returns the whole older catalog with its schemas, including operations this service no longer answers, so don't treat a listed name as served. An unserved name, including every agents.* operation, productions.run, jobs.*, compute.* and capabilities.*, answers HTTP 501 operation_not_ported. Use the session API and the tools for new work.

Schemas

The operation list on this page reads the service's live /openapi.json, which lists every route. For argument schemas, use the tool listing: GET /v1/tools (with a key) returns each tool's name, scope, summary and args_schema, and an MCP host sees the same schemas in tools/list. Session request and response shapes are described in Make an ad.

curl --fail-with-body https://api.wavemaker.io/openapi.json

MCP setup · SDKs · Errors · Capability map