API v1
Agents
Agents Invocation

Invoke Agent (Stream)

Invoke an AI agent with real-time streaming. Returns Server-Sent Events (SSE) for live task updates.

post/v1/agents/{agent_id}/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

The agent/workflow version to invoke. default = latest

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.

source_node_type'workbench' | 'sdk' | 'task' | 'assistant' | 'webhook' | 'mcp' | 'a2a' | 'telegram' | 'slack' | 'whatsapp' | 'ms-teams' | 'email' | 'api'
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.