OpenAPI reference¶

wes-contract publishes its REST surface as a single OpenAPI 3.1 document. The OpenAPI is the authoritative source for endpoint paths, request/response schemas, and the error catalog. The pages on this site explain the model; the OpenAPI tells you the exact field types.

API portal¶

Open the full API portal →

Three-pane Redoc rendering of the OpenAPI 3.1 contract — sticky navigation, per-operation deep links, auto-generated curl / JS / Python / Java request samples, collapsible nested schemas. Single self-contained HTML; works offline.

Raw sources¶

Artifact	Location
OpenAPI 3.1 source	`SiriusVoyager/wes-contract:openapi/v1/wms-wes.yaml`
Pre-rendered Redoc HTML (single-file, offline-friendly)	`SiriusVoyager/wes-contract:dist/wms-wes-redoc.html`

Fetch the raw OpenAPI document:

curl -L https://raw.githubusercontent.com/SiriusVoyager/wes-contract/master/openapi/v1/wms-wes.yaml \
  > wms-wes.yaml

The pre-rendered Redoc HTML ships alongside the source so a partner can clone the repo, double-click dist/wms-wes-redoc.html, and have the full API portal in a browser without any build step or server.

Versioning¶

Surface	Version axis
Major	URL segment (`/wes/v1/`, future `/wes/v2/`).
Minor	Field-level additions (always optional).
Patch	Clarifications, doc fixes, no schema change.

Consumers pin to a minor (e.g. wes-contract:1.2.0) and upgrade deliberately. Pinning to latest makes CI non-deterministic — don’t.

The full version compatibility surface is documented in WMS ADR-0022 and WMS ADR-0023.

Generated clients and server stubs¶

The wes-contract repo’s CI generates and publishes:

Language	Package	Use for
Java	`com.flexgalaxy:wes-contract-java` (Maven)	Spring Boot 4 services on the planner or executor side.
Python	`wes-contract` (PyPI under FG.AI’s index)	FastAPI services, integration scripts.
TypeScript	`@fgai/wes-contract` (CodeArtifact)	Browser-side dashboards consuming planner state.

The Java client is the openapi-generator spring generator with useJakartaEe=true + useSpringBoot3=true. The Python client is the python generator with library=urllib3. The TypeScript output is type definitions only — generated clients in the browser are discouraged because of bundle size.

Local generation¶

If you prefer to regenerate against a specific tag:

docker run --rm -v "${PWD}:/local" \
  openapitools/openapi-generator-cli:v7.16.0 \
  generate \
    -i /local/wms-wes.yaml \
    -g spring \
    -o /local/out \
    --additional-properties=useJakartaEe=true,useSpringBoot3=true,openApiNullable=false

Replace -g spring with python, typescript-fetch, or another supported generator as needed.

Schema cross-reference¶

The OpenAPI is organized by tag matching the families on this site:

OpenAPI tag	Pages on this site
`dispatch`	Dispatch
`realtime`	Realtime
`confirmation`	Confirmation
`webhooks`	Dispatch — webhook payload shape
`health`	Rollout

Component schemas — DocumentRef, Movement, Exception, WorkStatus, Capacity, ShiftSummary, CycleCount, InventorySnapshot, WindowKey, DispatchEvent, Routing, Operation, ProblemDetails — are shared across tags. Each is documented inline in the OpenAPI.