Gateway, Tools, and MCP API

These endpoints are how code outside the SOIT console calls a workspace's models and tools. Every call is a governed run. For concepts and configuration, see OpenAI-Compatible Gateway and MCP Server. This page describes v1.3.0, with the changes in v1.4.0, v1.5.0, and v1.6.0 marked.

Prefixes

/v1              OpenAI-compatible gateway (since v1.2.0), and the Anthropic Messages API at /v1/messages (since v1.5.0)
/api/v1/tools    direct tool calls (since v1.3.0)
/mcp             MCP server (since v1.3.0)

New in v1.4.0: a process started with SOIT_ROLE=gateway serves only these prefixes, the /.well-known discovery metadata of /mcp, and /health and /metrics; every other path answers 404 there. See Running the gateway on its own.

Authentication

• Send a SOIT API key as Authorization: Bearer sk_…. SOIT's API also accepts the key in X-API-Key, which is what the Anthropic SDKs send to /v1/messages.
• The key's scopes (read, write, admin) cap what it may do below its owner's role; calling models and tools needs write. POST /v1/messages/count_tokens, which calls no model, needs read.
• A signed-in session works too; over /mcp it names the workspace in X-Workspace-Id.
• A key issued to a service principal authenticates as the principal.

/v1 endpoints

• The model field takes a model ref (model:{provider}:{model}) or a virtual model (vmodel:{slug}).
• Fields SOIT does not know are ignored rather than refused. From v1.4.0, OpenAI image parameters SOIT knows but does not send (style, moderation, output_compression, partial_images, stream, and input_fidelity on edits) are accepted at their defaults and refused with 400 at any other value. See Image options.
• On models reached through OpenAI's Responses API (the GPT-5.5 family on an openai provider), stop is refused because that API cannot honour it, and seed is not sent.
• Not served: the Responses API (/v1/responses), Assistants, files, audio, batch, and fine-tuning, and Anthropic's Message Batches and Files APIs.
• On /v1/messages, top_k, metadata, service_tier, thinking, and cache_control are accepted and not sent, and disable_parallel_tool_use in tool_choice likewise; the anthropic-version and anthropic-beta headers are accepted and not interpreted. A document or other content block SOIT cannot carry, an image inside a tool_result, and tools Anthropic runs itself are refused with 400 naming them.

Response headers and ids

• x-soit-run-id names the run the call became. A chat completion's id is chatcmpl-{run id}, and an Anthropic message's id is msg_{run id}.
• The API lists X-SOIT-Run-Id in Access-Control-Expose-Headers, so a browser on another origin can read it.

Errors

Refusals under /v1 use OpenAI's error body without SOIT's envelope, so SDKs raise their usual exception classes:

{"error": {"message", "type", "param", "code"}}

code is SOIT's error code in lower case.

pricing_not_configured is answered before the provider is called, and a virtual model moves on to a priced target first; see Calls with no price.

Anthropic errors

New in v1.5.0. Under /v1/messages, refusals use Anthropic's body instead, so the Anthropic SDKs raise their usual exception classes:

{"type": "error", "error": {"type", "message"}}

The causes are those of the table above. A request that fails validation names the fields, as Anthropic's API does (max_tokens: Field required). A failure after a stream has started arrives as an error event, since the status line is already sent. | 429 | rate_limit_error | A rate limit or quota; Retry-After says when to try again | | 5xx | api_error | The provider failed or timed out, and no virtual model target was left to try |

Streams

A streamed response starts when the model's first chunk arrives, so a refusal before the stream answers with its own status code. A failure part way through ends the stream with an OpenAI error event. A stream the client abandons fails its run with CLIENT_DISCONNECTED. From v1.4.0 every stream that reached the provider is charged, with an estimate flagged usage_estimated when the provider's usage never came.

A streamed /v1/messages call (v1.5.0) uses Anthropic's named events: message_start, ping, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop. message_start carries SOIT's estimate of the prompt's tokens, and message_delta the provider's count once it is known.

Rate limits

A call over a rate limit or a daily quota answers 429 with a Retry-After header and the code RATE_LIMIT_EXCEEDED (lower case under /v1). Per-key limits — calls per minute, calls per 24 hours, tokens per UTC day — apply on top of the key owner's own limits. From v1.4.0 the call limits count a key's tool calls through /api/v1/tools and /mcp as well as its model calls, and a refusal names the limit in details.quota (per_minute, daily_requests). A call from an address or to a model the key does not allow answers 403. See Per-key limits.

Tools

These endpoints answer in SOIT's envelope, {"success": true, "data": {...}}, not OpenAI's. data carries run_id, status (succeeded, failed, waiting_approval, or rejected), result or error, idempotency_key, and replayed. The run is also named in x-soit-run-id.

• Idempotency. The same Idempotency-Key returns the recorded outcome (replayed: true) without calling the tool again. Keys belong to the caller, so two API keys never share one. Without a key, SOIT assigns one and returns it in the Idempotency-Key response header.
• Approval. Once a reviewer decides in Govern › Approvals, send the same call with the same key: an approved call runs and returns its result, a rejected one returns status: rejected and never runs. Only the arguments that were put up for approval can run.

MCP

/mcp and /.well-known/* answer their protocols' own shapes, not SOIT's envelope. Protocol versions, headers, and error codes are covered in MCP Server.

Related endpoints

See Identity API, ModelHub API, Runs, Tasks, and Observe API, and Budgets and Cost for the full families.