http://127.0.0.1:8088 locally. All /v1 routes use
Authorization: Bearer <WMS credential>. Tenant, actor, and role come from API-key configuration
or verified WorkOS membership mappings; caller-supplied identity fields cannot change them.
Core REST routes
History returns
{items:[{cursor,data}],next_cursor}. Preserve next_cursor as before for
the next page. The operational snapshot bounds recent/completed work; use detail and history
routes when reviewing older evidence.
Commands and recovery
This example shows the envelope for creating a catalog product. An administrator must replace the version with the actual reviewed facility version and persist the original body before posting to/v1/warehouses/{id}/commands:
{replayed:false,result:{entity_id,version,type}}.
An exact committed retry returns the original result with replayed:true, even after later
warehouse work. A different body or actor under the same key conflicts.
For supported physical commands, optional resource_versions can bind the exact stock/work
resources reviewed in a snapshot. Copy the complete required scope; do not construct a partial
map. Omitting it retains the warehouse-wide version fence.
After a timeout or unreadable response:
- Retain the original facility URI, actor, request ID, body, and reviewed versions.
- Read the original command receipt.
{found:false}alone does not establish non-commitment. - Recover using the exact original envelope. Do not repeat a physical action or generate a replacement request merely because its response was lost.
- Create a new request only after establishing the previous outcome and reviewing current work.
command_outcome proving not_committed for stale
versions or changed resources. A client may retire a pending request only after validating
that proof against its complete original identity and version/resource scope. A generic 409
does not supply that proof. Native imports/transport/fulfillment use their separate
native request journal.
Native MCP connection
Connect an HTTP-capable MCP client tohttp://127.0.0.1:8088/mcp, or your HTTPS ingress
plus /mcp. Store an individual WMS bearer credential in the client’s secret storage and send
it on every request. The endpoint runs in the WMS API process and uses Streamable HTTP with
JSON responses and no retained transport sessions. It does not provide OAuth client
registration or a stdio launcher.
Discover tools through tools/list, then read wms_session and wms_warehouses before
selecting a facility with wms_snapshot. The visible catalog depends on the role.
Path identifiers are top-level tool arguments; JSON POST bodies go in
request. The tool
does not generate a request ID, refresh a version, or automatically retry a write. Tool
results expose structuredContent: {http_status, body}; business errors preserve the REST
status and set MCP isError. The MCP JSON-RPC ID is separate from the warehouse request ID.
Default MCP hosts are loopback and requests containing an Origin are denied by default.
For remote ingress configure WMS_MCP_JSON with explicit allowed host authorities and,
if needed, exact trusted origins. Origin configuration does not supply CORS or authentication.
Errors and source contract
Expect 401 for invalid credentials, 403 for forbidden roles, 404 for unknown/cross-tenant entities, 409 for conflicts, 422 for invalid transitions, and 503 for database unavailability. Malformed JSON/extraction failures can return non-JSON bodies; retain an uncertain write even when its response cannot be parsed. This is a source-derived core reference, checked October 20, 2026 againststateset-warehouse/src/api.rs, docs/api.md, and docs/mcp.md. Consult those repository
contracts and discovered schemas for the full command surface.
Next, verify your local facility
or configure the native OMS/TMS handoff.