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.
Authorizations
MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.
Body
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.
1 - 200The message to send, as the user.
1 - 8000Required to START a session; ignored when continuing one.
Continue this session. Omit to start a new one.
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.
Target this environment's servers. Mutually exclusive with serverIds. First turn only.
Target these project servers. Mutually exclusive with environmentId. First turn only. Server CONFIGS are never accepted — only ids the project already holds.
20First turn only.
8000First turn only — pinned to the session and reused on every continuation.
0 <= x <= 21 <= x <= 16read_only advertises only tools annotated readOnlyHint: true. auto advertises everything and MAY CAUSE REAL EXTERNAL SIDE EFFECTS. First turn only.
read_only, auto 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.
20Advertise 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.
100Cap 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.
0 <= x <= 16Response
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.
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.
Minted by the turn lease and used by the ingest dedupe, so it names the same turn in both.
api This turn's spans, inline.
read_only, auto Tools the model could see this turn.
Tools the tool policy withheld.
Set when this idempotencyKey replayed an already-completed turn. Nothing was spent.

