Stateless Chat

By default, chat is stateful: each (workspace × x-session-id) conversation is persisted server-side, and reusing the same x-session-id resumes it. Set statelessMode: true on the workspace to turn this off entirely — nothing about the conversation is stored, and the caller supplies prior turns on each request. This is configured on the workspace endpoints (POST /api/v1/mcp/workspaces and PATCH /api/v1/mcp/workspaces/{id}). The environment (sandbox/production) is always derived from the API key — sk_test_* keys operate on sandbox, sk_live_* on production.

Want to route the workspace through your own LLM key and model as well? See the Bring Your Own LLM guide. The two controls are independent and can be combined on the same workspace.

Enable stateless mode

curl -X PATCH https://api.routemcp.io/api/v1/mcp/workspaces/{id} \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "statelessMode": true }'

statelessMode is a workspace-level boolean (default false). It can also be set on create. It cannot be overridden per chat request.

What stops being stored

When statelessMode is true, POST /api/v1/mcp/{workspaceId}/chat persists nothing:

no chat session is created or looked up (the x-session-id header is ignored),
no messages are stored,
no tool inputs/outputs are stored,
no end-user context is written.

What still happens:

Usage metadata (token and request counts) is still recorded for billing.
Analytics events are content-free (no message text is captured).
context is still injected into the agent for that request, but it is not stored.

Supplying history

Because nothing is persisted, the caller supplies prior turns on every request via the history array. The current message stays in the normal message field — history is prior turns only.

curl -X POST https://api.routemcp.io/api/v1/mcp/{workspaceId}/chat \
  -H "Authorization: Bearer sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "And which one has the most stars?",
    "history": [
      { "role": "user", "message": "What repos do I have?" },
      { "role": "assistant", "message": "You have 3 repositories: api, web, and docs." }
    ]
  }'

Field	Type	Notes
`history`	array of `{ role, message }`	Prior turns only (exclude the current message). `role` is `"user"` or `"assistant"`. Up to 200 items; each item’s `message` is capped at ~50,000 characters.

history is accepted only when the workspace is in statelessMode. Sending history to a non-stateless workspace returns 400 — so the caller can never silently have its supplied turns ignored.

In stateless mode there is no per-conversation end-user identity, so tool/provider connections resolve at the workspace level — every stateless call to the workspace shares the same connections.

The streamed response shape is identical to stateful chat — see the chat endpoint reference for the SSE event types.

Getting Started

Guides

References

Changelog

Enable stateless mode

What stops being stored

Supplying history

​Enable stateless mode

​What stops being stored

​Supplying history

Enable stateless mode

What stops being stored

Supplying history