Skip to main content
Push user input into a session and run one turn. The blocking endpoint performs recall → model → tools → persist, then returns a single turn object.

Endpoint

Authentication

Authorization: Bearer <api_key> or Authorization: ApiKey <key>. Optional if AGENT_CLOUD_API_KEY is unset.

Path parameters

string
required
Session identifier.

Request body

Provide text via input or structured content parts. Empty input returns 400.
string
Plain-text user input (short form).
array
OpenAI-shaped parts, for example [{"type":"input_text","text":"..."}].
string
Optional type tag; defaults to treating the body as a message.

Response

Returns a agent.session.turn object:
string
Turn id (turn_<hex>).
string
Always agent.session.turn.
string
Parent session.
string
Agent that ran the turn.
string
Typically completed (or failed / cancelled / in_progress).
string
Assistant output text when completed.
integer
Epoch milliseconds.
integer
Epoch milliseconds when finished.