OpenAPI 3.1 for Generative Media and Workflow APIs

OpenAPI is the map; JSON Schema on each slug is the territory. Wavemaker ships a single OpenAPI 3.1 document so gateways, codegen, and agents understand auth, paths, and shared request envelopes on the workflow API — while each published workflow still exposes its own input_schema for typed runs. This post is for platform integrators building clients and policy — not a tutorial on POST /videos (Automate video creation with the API).

Fetch and pin the contract

curl -sO https://api.wavemaker.io/api/v1/openapi.json

Pin the file hash in CI. Breaking API changes bump version notes in public API docs — diff openapi.json on upgrade like any dependency.

Companion artifacts:

URL	Purpose
/api/v1/openapi.json	HTTP routes, security schemes, shared components
/api/v1/workflow-spec-schema	Authoring + validating WorkflowSpec JSON
/api/v1/w/{slug}	Per-product input JSON Schema + economics

Generative media adds async 202 patterns, Idempotency-Key headers, and webhook fields everywhere — OpenAPI documents these once; slug posts repeat the semantics in Idempotency and webhooks.

What OpenAPI covers well

• Kernel runs: POST /workflows/{id}/runs, POST /w/{slug}/runs, estimates, approval, cancel, batch get.
• Builder: compile, save, publish, list specs, version history.
• Training Studio: datasets, jobs, evaluations (see model assets doc).
• Security: Bearer API keys; browser OAuth documented narratively on /mcp.

Import into Insomnia, Postman, or openapi-generator for TypeScript, Go, or Python clients. Set base URL https://api.wavemaker.io/api/v1.

What OpenAPI cannot enumerate

Hub has unbounded published slugs — each with distinct inputs. OpenAPI describes:

POST /w/{slug}/runs:
  parameters: [slug]
  requestBody:
    content:
      application/json:
        schema: { ... generic kernel run body ... }

Your codegen produces RunRequest with inputs: object — refine by fetching each slug’s input_schema (JSON Schema typed workflow inputs). Some teams codegen a two-layer client: platform client from OpenAPI + slug-specific wrappers checked in per integration.

WorkflowSpec validation in CI

Programmatic authors should not rely on OpenAPI alone:

curl -X POST https://api.wavemaker.io/api/v1/workflows/compile \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @spec.json

workflow-spec-schema + compile catches block param mismatches before publish. OpenAPI tells you compile exists; WorkflowSpec schema tells you what to send.

Staging vs production base URLs

OpenAPI describes paths relative to /api/v1. Staging integrators use https://api-staging.wavemaker.io/api/v1/openapi.json with staging keys — never point production codegen at staging hosts in release artifacts. Feature flags (feature flags doc) may gate routes; OpenAPI lists routes that exist in build, while KV may disable behavior — handle 503 workflowPlatformEnabled style responses in clients.

Component reuse in openapi.json

Shared schemas typically include:

• KernelRun — status enum, credits fields, metadata bag
• EstimateLineItem — generation, byok_fee, premium, memo_hit
• Error — structured code + message + optional details array

Codegen should import components rather than duplicating inline objects on slug routes. When Wavemaker adds fields (backward compatible), clients ignoring unknown keys survive; strict parsers should allow additionalProperties where OpenAPI marks them.

Documenting webhooks in OpenAPI vs reality

OpenAPI describes webhook_url on request bodies; delivery is server-push HTTP to your infrastructure — not a path in openapi.json. Document internal handler contracts separately. Event type strings (kernel_run.completed) are stable; payload fields may gain optional keys — verify with fixture tests.

Managed video section of the same document

The openapi.json file includes POST /videos and refinement routes for the composer product. Workflow-only integrators can exclude those tags in codegen filters. Conversely, teams bridging both products generate one client with two service classes — share Bearer auth, separate idempotency key namespaces per route family to avoid accidental replay across products.

Stale spec detection

Schedule weekly curl of openapi.json hash in CI; on change, open a renovate-style PR updating generated clients. Pair with public API human changelog for semantic changes (new required fields, renamed enums).

Generative-media-specific OpenAPI patterns

Pattern	OpenAPI expression	Integrator note
Async dispatch	202 + run id	Poll or webhook
Idempotency	header parameter	Required on retries
Webhooks	body fields	HMAC verify on receipt
Credit hold	response credits_held	Settles on completion
Version pin	optional version integer	Freezes graph + input promotion

Managed video routes (POST /videos) live in the same document but different product lane — workflow integrators can ignore them unless bridging both products.

Agents and LLM context

Feed models:

1. openapi.json (truncated to kernel + slug sections if context-limited)
2. llms.txt curated links
3. Per-slug input_schema when calling one product

Builder MCP (?tools=builder) reduces raw HTTP — see MCP builder mode deep dive. OpenAPI remains the audit artifact for security review.

Estimate / quote before a credit hold on a slug run.

Gateway and enterprise patterns

• API management: import OpenAPI, attach rate limits, mTLS termination at your edge, forward Bearer to Wavemaker.
• Contract tests: schemathesis or Dredd against staging keys — use estimate endpoints to avoid credit spend.
• Secret hygiene: OpenAPI describes webhook_secret fields — never log request bodies containing secrets.

Exporting OpenAPI fragments for slug routes

Some API gateways want a trimmed spec containing only /w/{slug} paths. Filter openapi.json tags programmatically — keep securitySchemes and shared components for KernelRun. Regenerate trim on each openapi hash bump.

LLM tool-use vs OpenAPI

Models with native OpenAPI tool modes can call REST directly without MCP — useful for server agents. Builder MCP still wins in IDEs with OAuth already solved. Hybrid: MCP for auth session, OpenAPI for nightly batch jobs on same org.

Integrator playbook: first week with openapi.json

Day 1 — Inventory: Download openapi.json and workflow-spec-schema; tag-filter kernel and /w/ paths; list which slugs your team will call from Hub favorites.

Day 2 — Schema snapshot: For each slug, curl GET /w/{slug} and commit input_schema beside fixture JSON; wire Ajv or zod validation in unit tests.

Day 3 — Estimate CI: Add PR job calling POST /w/{slug}/estimate with fixtures — catches creator publish drift before merge (Slug-run workflows from CI).

Day 4 — Idempotent smoke: Main-branch job with Idempotency-Key and webhook to staging receiver; verify HMAC (Idempotency and webhooks).

Day 5 — Client codegen: Generate typed client from openapi; wrap slug submits in helper that injects metadata and idempotency headers.

This sequence avoids learning billing surprises in production — estimates and compile routes stay free while you harden contracts.

OpenAPI and JSON Schema together in RAG pipelines

Retrieval-augmented agents should store openapi.json chunks for how to authenticate and which path to call, plus per-slug schema chunks for what to put in inputs. Mixing them in one embedding index without metadata causes wrong field names at runtime — tag documents with doc_type: platform vs doc_type: slug-product-teaser. Refresh slug chunks when Hub creators publish; refresh platform chunks when openapi hash changes in CI.

Versioning and backward compatibility

Wavemaker adds optional response fields and new routes more often than it removes them. Pin openapi hash in CI; on upgrade, run contract tests against estimate endpoints first (free), then a single idempotent smoke run. Breaking changes to required request fields appear in changelog and public API docs — openapi alone does not replace release notes for semantic behavior (memo rules, moderation, cap changes).

Where to go next

• Slug run walkthrough: Workflows as API endpoints
• /workflow-api landing
• Dynamic agent tools: Dynamic MCP tools for workflows
• BYOK fee lines in estimates: BYOK AI media generation