OpenAPI reference¶

The WMS ingest API is published as a single OpenAPI 3.1 document. 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.

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/wms:openapi/v1/wms-ingest.yaml`
Pre-rendered Redoc HTML (single-file, offline-friendly)	`SiriusVoyager/wms:dist/wms-ingest-redoc.html`

Fetch the raw OpenAPI document:

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

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

Live spec¶

Each FG.AI WMS service publishes its OpenAPI document at the standard springdoc path /v3/api-docs:

Dev — https://dev-api.flexgalaxy.com/wms-ingest/v3/api-docs
Production (international) — https://api.flexgalaxy.ai/wms-ingest/v3/api-docs
Production (China) — https://api.flexgalaxy.com/wms-ingest/v3/api-docs

Fetch the live spec:

curl -H "Authorization: Bearer ${TOKEN}" \
  https://dev-api.flexgalaxy.com/wms-ingest/v3/api-docs \
  > wms-ingest.openapi.json

The live spec is generated from the running service’s annotated controllers, so it is always in sync with the deployed binary. If a field appears in the live spec but not in older client SDKs, regenerate your client.

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

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.