Every Wavemaker Workflow Is Now an API Endpoint

Publishing a workflow as an API endpoint means your Hub app at /w/{slug} and your backend integration share one contract: typed inputs, a free estimate, idempotent submit, and signed lifecycle webhooks. The workflow API landing collects the operator-facing overview; this post is the integrator walkthrough — slug runs, not managed POST /videos (that path stays in Automate video creation with the API).

The 60-second version

# What does this workflow take?
curl https://api.wavemaker.io/api/v1/w/product-teaser \
  -H "Authorization: Bearer mcp_your_key"
# → { workflow: { inputs: [...], input_schema: { JSON Schema }, run_url, estimate_url, ... } }

# What will it cost?
curl -X POST https://api.wavemaker.io/api/v1/w/product-teaser/estimate \
  -H "Authorization: Bearer mcp_your_key" -H "Content-Type: application/json" \
  -d '{ "inputs": { "product_url": "https://myshop.com/p/123" } }'

# Run it.
curl -X POST https://api.wavemaker.io/api/v1/w/product-teaser/runs \
  -H "Authorization: Bearer mcp_your_key" -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-123-v1" \
  -d '{
    "inputs":   { "product_url": "https://myshop.com/p/123" },
    "metadata": { "sku": "123", "batch": "2026-07" },
    "webhook_url": "https://myapp.example/hooks/wavemaker",
    "webhook_secret": "whsec_rotate_me"
  }'
# → 202 { "run": { "run_id": "…", "status": "queued", "credits_held": 84, ... } }

When the run finishes, your endpoint receives a signed kernel_run.completed POST carrying the outputs, the settled credits, and your metadata — no polling loop required.

Why slug runs instead of copying the graph

Integrators often start by forking a workflow spec id into their own org. That works for private pipelines, but products usually want the creator’s published version — premium pricing, royalty lines, and moderation already applied. Slug runs execute the published graph for that Hub listing:

• Open workflows are forkable; foreign runs still attribute royalties on settled platform credits.
• Premium workflows bill the creator’s per-run price; the public API never exposes premium graph internals — only inputs, estimates, and outputs.

You do not need the underlying workflow_spec_id in your config. Marketing can change cover copy on /w/{slug} while your integration keeps calling the same URL.

Use case 1: per-SKU video at catalog scale

The classic batch job: one video per product, driven by a nightly cron. Two things usually go wrong at scale — duplicate submissions when the job retries, and losing track of which run belongs to which SKU. Both are solved in the request itself:

import requests

API = "https://api.wavemaker.io/api/v1"
HEADERS = {"Authorization: Bearer mcp_your_key"}

for sku in catalog:
    requests.post(
        f"{API}/w/product-teaser/runs",
        headers={**HEADERS, "Idempotency-Key": f"teaser-{sku.id}-{sku.content_hash}"},
        json={
            "inputs": {"product_url": sku.url},
            "metadata": {"sku": sku.id},
            "webhook_url": "https://myapp.example/hooks/wavemaker",
            "webhook_secret": WEBHOOK_SECRET,
        },
    )

• The Idempotency-Key is permanent per organization: if the cron crashes halfway and reruns, already-submitted SKUs replay their original run (idempotent_replayed: true, HTTP 200) instead of double-charging. Keying on a content hash means a changed product resubmits naturally.
• The metadata object (up to 16 string entries) is echoed on every read and in every webhook — your handler routes the finished video to the right SKU without a lookup table.

Need to check a batch without a webhook? GET /api/v1/kernel-runs?ids=a,b,c reads up to 20 runs in one call. Deeper treatment of keys and HMAC verification lives in Idempotency and webhooks for media APIs.

Use case 2: webhooks with approval gates

Workflows can include an approval gate — a human-in-the-loop pause before the expensive steps run. Over the API this becomes a webhook round-trip:

1. Your run parks: you receive kernel_run.awaiting_approval with an instance_key.
2. Your app shows the preview to a human (or applies its own policy).
3. You POST the decision:

curl -X POST https://api.wavemaker.io/api/v1/kernel-runs/$RUN_ID/approval \
  -H "Authorization: Bearer mcp_your_key" -H "Content-Type: application/json" \
  -d '{ "instance_key": "…from the webhook…", "decision": "approved" }'

Every webhook is HMAC-signed when you supply a webhook_secret (X-Webhook-Signature: v1,<hex> over <id>.<timestamp>.<body> — same scheme as all Wavemaker webhooks), and X-Webhook-ID gives you an idempotent-processing handle on your side.

Use case 3: pin the version, ship with confidence

A workflow’s creator can keep iterating after you integrate. Your integration shouldn’t care — unless you want it to:

• Default: runs use the latest published version. Creators’ drafts never affect you.
• Pinned: pass "version": 3 in the body and your integration runs the exact graph you tested, forever. New published versions wait until you bump the pin.

Version pins pair well with CI: run smoke tests against version: N, promote the pin in config only after green. See Run Hub workflows from CI for GitHub Actions patterns that never touch managed video endpoints.

Use case 4: validate before you spend

Two contract endpoints make the whole surface machine-consumable — no auth required:

• GET /api/v1/openapi.json — OpenAPI 3.1 for every workflow-platform route. Generate a typed client, wire it into your API gateway, or hand it to an AI agent as context. We unpack generative-media quirks in OpenAPI for generative media.
• GET /api/v1/workflow-spec-schema — the JSON Schema for workflow definitions themselves. Building workflows programmatically? Validate in CI with POST /api/v1/workflows/compile (stateless — nothing saved, nothing charged) and catch a broken spec before it ships:

curl -X POST https://api.wavemaker.io/api/v1/workflows/compile \
  -H "Authorization: Bearer mcp_your_key" -H "Content-Type: application/json" \
  -d @workflow-spec.json
# → { compiles: true, estimated_credits: 84, warnings: [] }   (or errors with node-level diagnostics)

Input shapes for runners come from promoted workflow inputs — not hand-maintained OpenAPI fragments. Read JSON Schema typed workflow inputs for how $input fields compile into the schema on GET /w/{slug}.

Billing that respects retries and iteration

Every run holds credits up front (the workflow’s cost envelope plus any creator premium) and settles to actual usage on completion — cancelled runs keep only what actually executed. Estimates (POST /w/{slug}/estimate) are free and itemized: per-capability generation credits, BYOK fees if you route steps through your own provider keys, and the creator’s premium, so you can show your own users a real price before submitting.

Upstream blocks can memo-hit when inputs unchanged — changing only the last step should not re-bill scraping and six reviewed frames. That behavior is org-scoped and auditable per node; see Memoized workflow runs. Idempotency keys protect submit retries; memoization protects creative retries — both matter in production.

Operational limits worth planning for

• Daily cap: 200 kernel runs per org per rolling 24h → HTTP 429 KERNEL_DAILY_RUN_CAP. Batch jobs should backoff and surface the cap to operators.
• Premium graphs: responses include pricing lines, never block-level internals — design observability around run nodes and webhooks, not exported Comfy graphs.
• Auth: API keys use Bearer tokens; browser /w/{slug} uses session auth for runs but exposes the same JSON Schema to anonymous visitors for discovery.

Published Hub app page at /w/{slug} with typed inputs and Run.

Where to go next

• Endpoint reference and copy-paste curl: /developers#workflows and /workflow-api
• Prefer an agent over code? The same surface is exposed over MCP — including dynamic wf_<slug> tools. See Drive Wavemaker Workflows from Your AI Agent and the MCP product page.
• Ship the listing first: Publish your AI workflow as an app
• Building workflows in the app: What is an AI workflow? and Workflow platform field guide