API v1

Agents

Agents Invocation

Invoke Agent (Async)

Invoke an AI agent asynchronously. Returns immediately with task ID for later polling.

post/v1/agents/{agent_id}/invoke/async

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.

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

background_auth_eligibleboolean

idstring required

agent_idstring required

organization_idstring required

internal_statusstring nullable

last_executed_node_idstring nullable

agent_versionstring nullable

created_atstring date-time required

started_atstring date-time nullable

paused_atstring date-time nullable

finished_atstring date-time nullable

resultstring nullable

parent_executionstring nullable

conversation_idstring nullable

sub_executionsstring[] nullable

finished_sub_executionsstring[] nullable

should_update_parentboolean nullable

is_manually_stoppedboolean nullable

is_backgroundboolean nullable

payload_extensionobject nullable

sourcestring nullable

worker_idstring nullable

additional_contextstring nullable

instructions_overridestring nullable

expected_outputstring nullable

engagement_instructionsstring nullable

output_format_instructionsstring nullable

test_run_node_idstring nullable

is_orchestrationboolean nullable

is_gatewayboolean nullable

conversation_kind'direct' | 'gateway'

direct: the head row never runs a model turn, every message is one task on the agent; gateway: a router-era head.

is_appboolean nullable

is_desktopboolean nullable

device_idstring nullable

desktop_user_idstring nullable

verified_user_transportstring nullable

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

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

voice_idstring nullable

output_schemaobject nullable

events_streamingboolean nullable

used_mutating_toolsboolean nullable

is_continuousboolean nullable

mcp_serversobject[] nullable

triggering_agent_idstring nullable

titlestring nullable

think_mode'default' | 'harder'

disable_attachment_injectionboolean nullable

must_deep_planboolean nullable

short_summarystring nullable

execution_attemptsinteger nullable

user_tokensobject nullable

user_oidc_tokenstring nullable

return_metricsboolean nullable

llm_model_providerstring nullable

Snapshot of the LLM provider used for this execution (request override or agent default at run time).

llm_model_namestring nullable

Snapshot of the LLM model name used for this execution (request override or agent default at run time).

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

execution_kind'turn' | 'resident'

A turn ends when the CLI answers; a resident process stays Executing until the agent finishes it.

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

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

permission_mode'full' | 'gated'

builtin_toolsobject nullable

Harness agents only: the resolved built-in tool sets this execution runs with, {"harness": {"enabled": bool}, "xpander": {"enabled": bool}}; inherited per half by later tasks of the conversation unless one names its own.

tool_call_limitinteger nullable

Max tool calls for this execution; unset leaves the agent's own ceiling in place.

archived_atstring date-time nullable

When the conversation was archived; unset while it is live.

archived_bystring nullable

Who archived the conversation (user id), when it was.

archived_by_agent_idstring nullable

The agent that archived the conversation on its own, when one did; unset when a person archived it.

deleted_atstring date-time nullable

When the user deleted the conversation; a deleted conversation never mirrors to history again and reads as not found.

waiting_reasonstring nullable required

Why a live resident process is waiting rather than working (plan_limit); None otherwise.

resumes_atstring date-time nullable required

When a waiting process resumes on its own (ISO), read from its booked wake; None otherwise.

Changes

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