Sign in
Chat sessions

Send one agent Playground message

Send one message to a project's MCP servers and get the model's reply plus the telemetry a participant in the conversation could not see: which tools ran, with what arguments, what each returned, per-call latency, and token usage.

Spends model credits per call. idempotencyKey is required and must be STABLE for the triggering intent — a fresh key per HTTP attempt deduplicates nothing, so a timeout-and-retry would run and bill the turn twice. With a stable key, a retry replays the completed turn.

Omit sessionId to start a session; pass the one this returns to continue it. Configuration (modelId, target, systemPrompt, toolMode) pins on the FIRST turn — a continuation that resends any of it is refused with details.reason: "CONFIG_ON_CONTINUATION".

Only sessions created through this endpoint may be continued through it (CONTINUATION_NOT_ALLOWED): appending to a human's live Playground session would interleave two writers on one transcript.

toolMode defaults to read_only, which advertises only tools the server annotated readOnlyHint: true. That hint is server-asserted, so read_only is a policy this host applies, not a guarantee it can verify. auto advertises everything and may cause real external side effects through arbitrary third-party tools.

post/chat-sessions/messages

Request body

idempotencyKeystring required

STABLE identity for this turn's intent — reuse it when retrying. A fresh key per attempt deduplicates nothing and will bill the turn twice. Printable ASCII only.

messagestring required

The message to send, as the user.

projectIdstring

Required to START a session; ignored when continuing one.

sessionIdstring

Continue this session. Omit to start a new one.

modelIdstring

Provider-prefixed model id, e.g. anthropic/claude-sonnet-5. Required on a first turn. A BARE id is rejected with details.reason: "MODEL_AMBIGUOUS" rather than guessed — an unprefixed id is indistinguishable from a local Ollama model, and guessing would spend on the wrong rail.

environmentIdstring

Target this environment's servers. Mutually exclusive with serverIds. First turn only.

serverIdsstring[]

Target these project servers. Mutually exclusive with environmentId. First turn only. Server CONFIGS are never accepted — only ids the project already holds.

systemPromptstring

First turn only.

temperaturenumber

First turn only — pinned to the session and reused on every continuation.

maxStepsinteger
toolMode'read_only' | 'auto'

read_only advertises only tools annotated readOnlyHint: true. auto advertises everything and MAY CAUSE REAL EXTERNAL SIDE EFFECTS. First turn only.

allowedServerIdsstring[]

Narrow THIS TURN to a subset of the target's servers. An empty array narrows to none and is rejected — omit the field to use the whole target. Per-turn, not pinned.

allowedToolsstring[]

Advertise only these tool names, for THIS TURN. An empty array advertises no tools at all — the same request as maxToolCalls: 0. Per-turn, not pinned.

maxToolCallsinteger

Cap the tool calls this turn may make, enforced at DISPATCH rather than by bounding steps (one step can emit several parallel calls). 0 advertises no tools at all.

Response

The turn ran. persisted.outcome reports whether the transcript landed — a turn that ran but failed to persist still spent, so this is a 200 with an honest persisted block rather than an error.

sessionIdstring nullable required

The one public session id. Pass it back to continue, and to the trace/detail reads. NULL only when the turn ran but its transcript did not persist — which persisted.outcome reports, and which must not be read as "nothing happened": the turn already spent.

turnIdstring required

Minted by the turn lease and used by the ingest dedupe, so it names the same turn in both.

replystring
finishReasonstring nullable
toolMode'read_only' | 'auto'
advertisedToolCountinteger

Tools the model could see this turn.

excludedToolCountinteger

Tools the tool policy withheld.

origin'api' required
replayboolean

Set when this idempotencyKey replayed an already-completed turn. Nothing was spent.

messagestring