Skip to main content
POST
Run one headless agent turn

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.

Path Parameters

projectId
string
required

ID of the hosted project that contains the server.

Body

application/json
messages
object[]
required

The conversation so far, oldest first. The caller owns state and resends the full history each turn. Each message content is capped at 8,000 characters AND 8,192 UTF-8 bytes; the whole history is additionally capped at 98,304 UTF-8 bytes (96 KB).

Required array length: 1 - 50 elements
idempotencyKey
string

A STABLE identity for the triggering event — not a fresh uuid per attempt. Each write the turn performs derives its own key from this one, so a retried turn re-issues the same mutations onto the same rows instead of authoring duplicates. Printable ASCII only (the value becomes a header on every write the turn issues). Omitting it preserves the older non-idempotent behaviour rather than being rejected.

Required string length: 1 - 200
conversationId
string

Where an approval control can be rendered for this turn (a channel, a thread, a DM). Its presence is what makes the GATED tools available at all: without somewhere to collect a click, the turn is not offered them, so the model never proposes an action nobody can approve.

Required string length: 1 - 64
slackChannelId
string

Slack-named spelling of conversationId. Both are accepted indefinitely; conversationId wins when both are sent.

Required string length: 1 - 64

Response

The completed turn.

reply
string
required

The assistant's final text for this turn.

toolCalls
object[]
required
createdResources
object[]
required

Resources the turn created, with app deep links.

proposedActions
object[]
required

Actions the turn wants to take but may not take on its own — they SPEND, or reach a third-party system. Nothing here has happened: each entry is a persisted proposal awaiting a human click. The actionId is all an approval control needs to carry, because the server holds what the action does; the remaining fields are for RENDERING only and must never be echoed back as instructions.

usage
object
required