Skip to main content
POST
Send one agent Playground message

Authorizations

Authorization
string
header
required

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

application/json
idempotencyKey
string
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.

Required string length: 1 - 200
message
string
required

The message to send, as the user.

Required string length: 1 - 8000
projectId
string

Required to START a session; ignored when continuing one.

sessionId
string

Continue this session. Omit to start a new one.

modelId
string

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.

environmentId
string

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

serverIds
string[]

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

Maximum array length: 20
systemPrompt
string

First turn only.

Maximum string length: 8000
temperature
number

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

Required range: 0 <= x <= 2
maxSteps
integer
Required range: 1 <= x <= 16
toolMode
enum<string>
default:read_only

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

Available options:
read_only,
auto
allowedServerIds
string[]

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.

Maximum array length: 20
allowedTools
string[]

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.

Maximum array length: 100
maxToolCalls
integer

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.

Required range: 0 <= x <= 16

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.

sessionId
string | null
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.

turnId
string
required

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

persisted
object
required
origin
enum<string>
required
Available options:
api
reply
string
finishReason
string | null
toolCalls
object[]
trace
object

This turn's spans, inline.

usage
object
model
object
toolMode
enum<string>
Available options:
read_only,
auto
advertisedToolCount
integer

Tools the model could see this turn.

excludedToolCount
integer

Tools the tool policy withheld.

replay
boolean

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

message
string