> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Warehouse REST API and MCP

> WMS authentication, core reads, versioned command envelopes, original-request recovery, and native HTTP MCP setup.

Use your deployed WMS API origin, or `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

| Method | Route | Purpose |
| - | - | - |
| GET | `/health` | Public process liveness |
| GET | `/ready` | Public bounded database readiness |
| GET | `/v1/session` | Identity, demo status, default facility, and integration configuration status |
| GET | `/v1/warehouses?limit=100` | Tenant facility directory; continue with returned `next_after` as `after` |
| GET | `/v1/warehouses/{id}` | Consistent operational snapshot and reviewed versions |
| GET | `/v1/warehouses/{id}/reconciliation` | Full movement, allocation, and receipt-line proof |
| GET | `/v1/warehouses/{id}/history/{kind}` | Cursor history for orders, receipts, movements, activity, or exceptions |
| GET | `/v1/warehouses/{id}/orders/{order_id}` | Canonical order detail, including archived work |
| POST | `/v1/warehouses/{id}/commands` | Atomic versioned warehouse command |
| GET | `/v1/warehouses/{id}/commands/{request_id}` | Original actor's committed command receipt |
| GET | `/v1/operations/health` | Operator/admin tenant-wide queue, native request, and exception summary |
| GET | `/v1/operations/metrics` | Administrator Prometheus snapshot |

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`:

```json theme={null}
{
  "request_id": "c62d2a33-b2ce-46a8-9f4e-b0d471b9cc7c",
  "expected_version": 0,
  "command": {
    "type": "create_product",
    "sku": "TEE-001",
    "name": "Cotton Tee",
    "category": "Apparel",
    "reorder_point": 20
  }
}
```

Request IDs contain 8–100 ASCII letters, digits, hyphens, or underscores. The body limit is
256 KiB. Successful commands return `{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:

1. Retain the original facility URI, actor, request ID, body, and reviewed versions.
2. Read the original command receipt. `{found:false}` alone does not establish non-commitment.
3. Recover using the exact original envelope. Do not repeat a physical action or generate a
   replacement request merely because its response was lost.
4. Create a new request only after establishing the previous outcome and reviewing current work.

Some conflicts include a definitive `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](/guides/oms-wms-tms#recover-the-original-handoff).

## Native MCP connection

Connect an HTTP-capable MCP client to **`http://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.

| Tools | Use |
| - | - |
| `wms_session`, `wms_warehouses`, `wms_snapshot` | Identify the principal and review a facility |
| `wms_order`, `wms_receipt`, `wms_history` | Inspect retained work and original history |
| `wms_lot_trace`, `wms_serials`, `wms_serial_history` | Review lot evidence and literal serial custody |
| `wms_reconciliation`, `wms_operations` | Inspect stock proofs and operational issues |
| `wms_icommerce_preview`, `wms_icommerce_inventory` | Read typed compatibility previews/projections with explicit mappings; these do not commit stock changes |
| `wms_command_receipt`, `wms_native_receipt` | Recover original requests |
| `wms_<command.type>` | Execute the corresponding canonical warehouse command |
| `wms_oms_orders`, `wms_import_oms`, `wms_transport`, `wms_oms_fulfillment` | Use configured native integrations |

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 against
`stateset-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](/stateset-warehouse/quickstart#verify-identity-and-facility)
or [configure the native OMS/TMS handoff](/guides/oms-wms-tms).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.