API v1

Agents

Agent Conversations

Run Conversation Turn (Stream)

Run one turn and stream every event over SSE: the head's task_created (its id is the conversation id), the task's task_created, the task's chunks, tool calls, plans and cards, then one task_finished for the head carrying the answer. Pass id = conversation_id to continue a conversation.

post/v1/agents/{agent_id}/conversations/invoke/stream

Request

Base URL
https://api.xpander.ai (the document declares no server; this is the origin it was published from)
Auth
API key in header x-api-key

Path parameters

agent_idstring required

Query parameters

versionstring nullable

Agent version to run.

sub_tasks'sync' | 'async' | 'auto'

How the agent's own sub-tasks run inside this turn (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the per-sub-task decision. The mode sticks to the conversation until changed.

Request body

idstring nullable

minted_conversation_idboolean nullable

normalized_id_fieldsstring[] nullable

payload_extensionobject nullable

parent_execution_idstring nullable

worker_idstring nullable

sourcestring nullable

output_format'text' | 'markdown' | 'json' | 'voice'

output_schemaobject nullable

run_locallyboolean nullable

additional_contextstring nullable

instructions_overridestring nullable

test_run_node_idstring nullable

expected_outputstring nullable

engagement_instructionsstring nullable

Channel engagement-rule action prompts for this turn, rendered into the gateway system context in addition to the agent's instructions.

output_format_instructionsstring nullable

Channel-binding output-format text for this turn, rendered into the gateway system context in addition to the agent's instructions.

events_streamingboolean nullable

mcp_serversobject[] nullable

triggering_agent_idstring nullable

titlestring nullable

think_mode'default' | 'harder'

disable_attachment_injectionboolean nullable

user_tokensobject nullable

user_oidc_tokenstring nullable

return_metricsboolean nullable

llm_model_providerstring nullable

Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.

llm_model_namestring nullable

Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.

llm_reasoning_effort'low' | 'medium' | 'high' | 'xhigh'

harness_cli'claude-code' | 'codex' | 'opencode' | 'xpander'

A CLI the harness container can run; chosen per conversation, never per agent.

permission_mode'full' | 'gated'

tool_call_limitinteger nullable

Max tool calls for this execution. The budget belongs to the work, not the agent: a scheduled run knows how much it is worth. Falls back to the agent's setting when unset.

is_appboolean nullable

verified_user_transportstring nullable

Transport that VERIFIED input.user this turn ('chat' = Bearer session, 'mcp' = OAuth). Set only by the services that resolved the user themselves and stripped from caller-supplied bodies; downstream consent gates key off it.

is_steeringboolean nullable

sub_tasks_mode'sync' | 'async' | 'auto'

channel_contextstring nullable

Pre-rendered cross-channel recency block for channel turns; the gateway appends it to the turn's context verbatim.

thread_contextstring nullable

Pre-rendered history of the channel thread this turn arrived in; the gateway appends it to the turn's context, and it never becomes part of the user's message.

attachment_contextstring nullable

Pre-rendered text a channel extracted from this message's attachments and links (OCR, transcripts, fetched pages, readable files); the gateway appends it to the turn's context, and it never becomes part of the user's message.

Response

Successful Response

unknown required

Changes

No recorded changes to this operation across all 4 revisions of this API.