OpenAPI reference¶

FG.AI WMS publishes OpenAPI 3.1 documents for core ingest surfaces and adapter surfaces. The OpenAPI is the authoritative source for endpoint paths, request/response schemas, and error catalogues. The pages on this site explain the model; the OpenAPI tells you the exact field types.

Surface	Used by	OpenAPI source	Redoc portal
`wms-ingest/v1` — partner-pushed master + documents + inventory (full bulk-ingest surface)	Path A (`wes-contract` direct), Path B (FlexSync connectors), 3PL EDI inbound, system-integrator bridges, AND Path C side partners for item-shape schemas (`Sku`, `Location`, `WorkOrder`, `ItemHeader`, `DocumentHeader`, `DocumentLine`)	`openapi/v1/wms-ingest.yaml`	Open ingest portal →
`wms-partners/v1` — partner-scoped read surface + partner-bearer-token auth	Path C side-partner integrations (per WMS ADR-0045)	`openapi/wms-partners/v1/wms-partners.yaml`	Open partner portal →
`wms-rta-adapter/v1` — adapter-owned SKU/location/work-order/cancel/label boundary	RTA and generic side partners using the adapter-boundary Path C model	`openapi/wms-rta-adapter/v1/wms-rta-adapter.yaml`	Open adapter portal →

For adapter-boundary side partners, generate clients against wms-rta-adapter/v1. This is the correct contract when FG.AI provides a partner-facing adapter API and the partner maps to that adapter rather than calling core WMS services directly.

Both portals are three-pane Redoc renderings 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
WMS ingest OpenAPI 3.1 source	`SiriusVoyager/wms:openapi/v1/wms-ingest.yaml`
WMS partners OpenAPI 3.1 source	`SiriusVoyager/wms:openapi/wms-partners/v1/wms-partners.yaml`
WMS RTA adapter OpenAPI 3.1 source	`SiriusVoyager/wms:openapi/wms-rta-adapter/v1/wms-rta-adapter.yaml`
Pre-rendered ingest Redoc HTML (single-file, offline-friendly)	`SiriusVoyager/wms:dist/wms-ingest-redoc.html`
Pre-rendered partner Redoc HTML (single-file, offline-friendly)	`SiriusVoyager/wms:dist/wms-partners-redoc.html`
Pre-rendered adapter Redoc HTML (single-file, offline-friendly)	`SiriusVoyager/wms:dist/wms-rta-adapter-redoc.html`

Fetch the raw OpenAPI documents:

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

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

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

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

Runtime spec¶

The static OpenAPI YAML files above are the published contract. Some running services may also expose a springdoc /v3/api-docs endpoint when the gateway route is enabled; do not depend on that endpoint unless the target environment has been verified.

Current dev note: https://dev-api.flexgalaxy.com/wms-ingest/v3/api-docs is not exposed through the dev gateway at this time. Use the static YAML or Redoc portal for client generation.

Fetch the static dev contract from GitHub:

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

If a runtime /v3/api-docs endpoint is later exposed, compare it against the static YAML before regenerating production clients.

Endpoint summary¶

Base path: /wms-ingest/v1

Method	Path	Purpose
`POST`	`/master/uoms`	Upsert UoMs
`POST`	`/master/skus`	Upsert SKUs
`POST`	`/master/boms`	Upsert BOMs
`POST`	`/master/locations`	Upsert warehouse / zone / bin
`POST`	`/master/addresses`	Upsert addresses (parties + locations)
`POST`	`/master/lots`	Upsert lots
`POST`	`/master/serials`	Upsert serials
`POST`	`/documents/purchase-orders`	Upsert POs
`POST`	`/documents/sales-orders`	Upsert SOs
`POST`	`/documents/receivers`	Upsert Receivers
`POST`	`/documents/shippers`	Upsert Shippers
`POST`	`/documents/work-orders`	Upsert Work Orders
`POST`	`/documents/transfer-orders`	Upsert Transfer Orders
`DELETE`	`/documents/{source_id}?type=…`	Cancel a document
`POST`	`/inventory/snapshot`	Submit full or partial snapshot
`POST`	`/inventory/movements`	Submit deltas during overlap
`GET`	`/jobs/{job_id}`	Job status
`GET`	`/jobs/{job_id}/errors`	Page through job errors
`GET`	`/mappings`	`source_id` → `internal_id`
`GET`	`/quarantine`	List quarantined items
`POST`	`/quarantine/{id}/release`	Operator override
`GET`	`/health`	Liveness / readiness
`GET`	`/capabilities`	Feature and version negotiation

Webhook payloads (FG.AI WMS → caller) are documented under the /webhooks/* paths in the OpenAPI; the caller hosts these endpoints.

Versioning¶

URL-segment versioning. The base path is /wms-ingest/v1. Future breaking changes ship as /wms-ingest/v2. Minor versions add optional fields; patch versions are bug-fixes and clarifications. Versions are stable: a v1 endpoint may add optional response fields but will not change existing field semantics.

Pin generated clients to a specific minor version snapshot of the service you target. Pin to latest only in ephemeral integration tests; do not pin to latest in production builds.

Generated clients¶

FG.AI publishes generated clients for the most common stacks:

Language	Package	Use for
Java	`com.flexgalaxy:wms-ingest-client-java`	Spring Boot 4 services pushing data into FG.AI WMS.
Python	`wms-ingest-client` (PyPI under FG.AI’s index)	FastAPI services, scripts, FlexSync connectors.
TypeScript	`@fgai/wms-ingest-client`	Browser-side admin tooling reading FG.AI state.

The Java client is the openapi-generator spring generator with useJakartaEe=true + useSpringBoot3=true. Python uses the python generator with library=urllib3.

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-ingest.openapi.json \
    -g spring \
    -o /local/out \
    --additional-properties=useJakartaEe=true,useSpringBoot3=true,openApiNullable=false

Swap -g spring for python, typescript-fetch, or another supported generator as needed.

Schema cross-reference¶

OpenAPI tag	Pages on this site
`master`	Entities, Identity mapping, Sync modes
`documents`	Entities, Sync modes
`inventory`	Entities, Rollout
`jobs`	Sync modes — bulk, Errors
`quarantine`	Normalization and quarantine
`webhooks`	Webhooks
`health`	Rollout
`wms-rta-adapter`	Side-partner adapter API

Component schemas — IngestEnvelope, ItemResult, BulkJob, Quarantine, Mapping, WebhookPayload, DocumentRef, Location, Sku, Uom, Bom, Lot, Serial, Address, Inventory*, Movement, ProblemDetails — are shared across tags. Each is documented inline in the OpenAPI.