Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
invoke
Invoke Agent (Sync)
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/invoke \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input": {
    "text": "",
    "files": [],
    "user": {
      "email": "<string>",
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "additional_attributes": {},
      "role": "member",
      "is_super_admin": false,
      "timezone": "<string>"
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_schema": {},
  "run_locally": false,
  "additional_context": "<string>",
  "instructions_override": "<string>",
  "test_run_node_id": "<string>",
  "expected_output": "<string>",
  "events_streaming": false,
  "mcp_servers": [],
  "triggering_agent_id": "<string>",
  "title": "<string>",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "user_tokens": {},
  "user_oidc_token": "<string>",
  "return_metrics": false,
  "llm_model_provider": "<string>",
  "llm_model_name": "<string>"
}
'
{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "",
    "files": [],
    "user": {
      "email": "<string>",
      "display_name": "<string>",
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "additional_attributes": {},
      "role": "member",
      "is_super_admin": false,
      "timezone": "<string>"
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "status": "pending",
  "internal_status": "<string>",
  "last_executed_node_id": "<string>",
  "agent_version": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "paused_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "result": "<string>",
  "parent_execution": "<string>",
  "sub_executions": [],
  "finished_sub_executions": [],
  "should_update_parent": false,
  "is_manually_stopped": false,
  "is_background": false,
  "payload_extension": {},
  "hitl_request": {
    "wait_node_id": "<string>"
  },
  "pending_eca_request": {
    "connector_name": "<string>",
    "auth_url": "<string>"
  },
  "source": "<string>",
  "worker_id": "<string>",
  "additional_context": "<string>",
  "instructions_override": "<string>",
  "expected_output": "<string>",
  "test_run_node_id": "<string>",
  "is_orchestration": false,
  "is_gateway": false,
  "output_format": "text",
  "voice_id": "<string>",
  "output_schema": {},
  "events_streaming": false,
  "used_mutating_tools": false,
  "is_continuous": false,
  "mcp_servers": [],
  "triggering_agent_id": "<string>",
  "title": "<string>",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "deep_planning": {
    "enabled": false,
    "enforce": false,
    "started": false,
    "question_raised": false,
    "tasks": []
  },
  "execution_attempts": 1,
  "user_tokens": {},
  "user_oidc_token": "<string>",
  "return_metrics": false,
  "tokens": {
    "completion_tokens": 0,
    "prompt_tokens": 0,
    "total_tokens": 0
  },
  "llm_model_provider": "<string>",
  "llm_model_name": "<string>"
}
Invoke an agent synchronously. The request blocks until the agent finishes (typically 5–30 seconds) and returns the completed task with the result. For longer-running tasks, use Invoke Agent (Async) or Invoke Agent (Stream).

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

input.text, input.user.id, and input.user.email are required. user_oidc_token is optional for MCP OAuth-backed tools.
​
input
object
required
​
user_oidc_token
string
Optional OIDC token for MCP OAuth-authenticated tools.
​
id
string
Thread ID for multi-turn conversations. Pass the id from a previous task’s response to continue the same conversation. The agent will have full context of all prior messages. If omitted, a new thread is created automatically.
​
disable_attachment_injection
boolean
default:"false"
When true, files passed in input.files are not injected into the LLM context window. The file URLs are still available to the agent’s tools, but the raw content won’t be prepended to the prompt.Use this when:
  • Files are large (would exceed the model’s context limit)
  • You want tools to process the files rather than the LLM reading them directly
  • You’re passing many files and don’t need them all in context
Default (false): file contents are downloaded, extracted, and injected directly into the LLM prompt as context.
​
think_mode
string
default:"default"
Controls the agent’s reasoning depth. default for standard reasoning, harder for deeper chain-of-thought analysis. Use harder for complex multi-step tasks that benefit from more deliberate planning.
​
instructions_override
string
Additional instructions appended to the agent’s system prompt for this invocation only. Use this to adjust behavior per-request without changing the agent’s configuration — for example, restricting output format, adding constraints, or changing tone.
​
additional_context
string
Extra context appended to the agent’s system prompt for this invocation only. Unlike instructions_override (which adds behavioral instructions), this supplies supplementary facts or context the agent should consider for this run — e.g. relevant background data, the current state of an external system, or a user’s recent activity.
​
expected_output
string
Natural-language description of the desired output (e.g., "A bulleted list of key findings"). Guides the agent’s response style.
​
llm_model_provider
string
Per-execution LLM provider override. Use the provider’s internal identifier (e.g. openai, anthropic, bedrock) from GET /v1/llm_providers. Omit to use the agent’s configured provider.
​
llm_model_name
string
Per-execution model override. Must be a valid model under the chosen provider (GET /v1/llm_providers/{provider}/models). Examples: claude-sonnet-4-6, gpt-5, gemini-2.0-flash. Omit to use the agent’s configured model.
​
llm_reasoning_effort
string
default:"medium"
Per-execution reasoning-effort override for reasoning-capable models (e.g. GPT-5). One of low, medium, high, xhigh. Omit to use the agent’s configured reasoning effort.

​
Query Parameters

​
version
string
Agent version to invoke. Defaults to the latest deployed version. Use "draft" to test undeployed changes.

​
Response

The response is the full task object. The key fields you’ll use:
​
id
string
Task/thread ID. Pass this back as id in your next request to continue the conversation.
​
status
string
completed, failed, error, or stopped
​
result
string
The agent’s response. If output_format is json, this is a JSON string — parse it with JSON.parse() or jq.
​
created_at
string
ISO 8601 timestamp when the task was created
​
finished_at
string
ISO 8601 timestamp when the task completed
​
llm_model_provider
string
Effective LLM provider used for this execution. Reflects the per-execution override when supplied, otherwise the agent’s configured provider.
​
llm_model_name
string
Effective model name used for this execution. Reflects the per-execution override when supplied, otherwise the agent’s configured model.
​
llm_reasoning_effort
string
Effective reasoning effort used for this execution. One of low, medium, high, xhigh. Reflects the per-execution override when supplied, otherwise the agent’s configured reasoning effort.

​
Simplest Possible Invoke

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "What is xpander.ai?"}}'
Extract just the result: 
curl -s ... | jq -r '.result'

​
Multi-Turn Conversation

Pass the id from the first response to continue the thread: 
# Turn 1
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Hi, my name is David and I work at xpander.ai"}}'

# Response includes: "id": "6525177e-06a1-4063-82fe-37382d2302a5"

# Turn 2 — pass the same id
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "What is my name and where do I work?"},
    "id": "6525177e-06a1-4063-82fe-37382d2302a5"
  }'

# Agent responds: "Your name is David and you work at xpander.ai."
The agent remembers all previous messages in the thread. Always reuse the same id for follow-ups.

​
With User Identity

Pass the required user fields so the agent can personalize responses and use identity-aware tools: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What is my user ID and email?",
      "user": {
        "id": "user-123",
        "email": "david@xpander.ai"
      }
    }
  }'

{
  "status": "completed",
  "result": "Your user ID is user-123 and your email is david@xpander.ai."
}
The user object is visible to the agent as context. Both id and email are required.

​
With MCP OAuth

Pass user_oidc_token when the agent uses MCP tools that require OAuth on behalf of the user: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "Create a calendar event for tomorrow at 10am",
      "user": {
        "id": "user-123",
        "email": "david@xpander.ai"
      }
    },
    "user_oidc_token": "USER_OIDC_TOKEN"
  }'

​
Processing Files

Files passed in input.files are downloaded and injected directly into the LLM context window by default. This works well for small-to-medium files: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What is the abstract of this paper?",
      "files": ["https://assets.xpanderai.io/static/pdf/bitcoin.pdf"]
    }
  }'

{
  "status": "completed",
  "result": "The abstract describes a peer-to-peer electronic cash system that enables direct online payments without financial institutions, solving the double-spending problem through a distributed network using proof-of-work and cryptographic signatures."
}
The 9-page Bitcoin whitepaper (above) processes successfully — its content fits within the model’s context window.

​
Large Files Fail with Direct Injection

Large files will exceed the model’s context limit and return an error: 
# This 185-page PDF will fail — too large for the context window
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What year was the Apple Macintosh introduced?",
      "files": ["https://assets.xpanderai.io/static/pdf/Introducing_the_Apple_Macintosh_1984.pdf"]
    }
  }'

{
  "status": "error",
  "result": "Error code: 413 - {'error': {'type': 'request_too_large', 'message': 'Request exceeds the maximum size'}}"
}
Files are injected into the LLM context by default. Documents over ~100 pages will typically exceed the model’s token limit. For large documents, use a Knowledge Base instead — add the document to a KB, attach it to the agent, and the agent will search it automatically via RAG.

​
Disable Context Injection

Set disable_attachment_injection: true to pass the file URL to the agent’s tools without injecting its content into the LLM prompt: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "Analyze this dataset",
      "files": ["https://example.com/data.csv"]
    },
    "disable_attachment_injection": true
  }'
With this flag, the file URL is available to the agent’s tools but the raw content is not prepended to the prompt. Use this when you want the agent’s tools to process the file rather than the LLM reading it directly.
For very large files (185+ pages), even disable_attachment_injection: true may not be enough — the file can exceed the HTTP request size limit before reaching the LLM. Use a Knowledge Base for production workflows with large documents.

​
Per-Request Instruction Override

Append instructions for this specific invocation without changing the agent’s configuration: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "Tell me about xpander pricing"},
    "title": "Pricing Inquiry",
    "instructions_override": "Always respond in exactly 2 sentences. Never use emojis."
  }'

{
  "status": "completed",
  "title": "Pricing Inquiry",
  "result": "xpander.ai offers two main pricing tiers: a Free plan with 2 serverless agents and 100 AI actions, and an In-House plan at $940/month for up to 10 agents and 200K actions. You can deploy on xpander's managed cloud or your own infrastructure."
}

​
Per-Execution LLM Override

Override the agent’s configured provider, model, or reasoning effort for a single invocation without mutating the agent. Useful for A/B testing models, routing specific requests to a stronger or cheaper model, or dialing up reasoning effort on complex prompts: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "Summarize the attached research paper"},
    "llm_model_provider": "openai",
    "llm_model_name": "gpt-5",
    "llm_reasoning_effort": "high"
  }'
All three fields are optional and independent — supply only the ones you want to override. Omitted fields fall back to the agent’s configured values. The response object includes the effective llm_model_provider, llm_model_name, and llm_reasoning_effort that were actually used, so downstream metrics and dashboards correctly attribute the run.

​
Structured JSON Output

Request structured output with a JSON Schema: 
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Look up Stripe"}}'
To configure output_format and output_schema for structured output, use the Update Agent endpoint or configure it in the dashboard under the Output tab.

​
Example Response

{
  "id": "6525177e-06a1-4063-82fe-37382d2302a5",
  "agent_id": "<agent-id>",
  "organization_id": "<org-id>",
  "status": "completed",
  "input": {
    "text": "What is xpander.ai in one sentence?",
  },
  "result": "xpander.ai is a full-stack platform for building, deploying, and running autonomous AI agents in production.",
  "source": "api",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "created_at": "2026-02-07T10:15:22.100233Z",
  "started_at": "2026-02-07T10:15:22.500000Z",
  "finished_at": "2026-02-07T10:15:28.997811Z",
  "execution_attempts": 1,
  "llm_model_provider": "anthropic",
  "llm_model_name": "claude-sonnet-4-6",
  "llm_reasoning_effort": "medium"
}

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Query Parameters

​
version
string | null

The agent/workflow version to invoke. default = latest

Body

application/json
​
input
AgentExecutionInput · object
required
​
id
string | null
​
payload_extension
Payload Extension · object
​
parent_execution_id
string | null
​
worker_id
string | null
​
source
string | null
​
output_format
enum<string> | null
Available options:
text,
markdown,
json,
voice
​
output_schema
Output Schema · object
​
run_locally
boolean | null
default:false
​
additional_context
string | null
​
instructions_override
string | null
​
test_run_node_id
string | null
​
expected_output
string | null
​
events_streaming
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null
​
think_mode
enum<string> | null
default:default
Available options:
default,
harder
​
disable_attachment_injection
boolean | null
default:false
​
user_tokens
User Tokens · object
​
user_oidc_token
string | null
​
return_metrics
boolean | null
default:false
​
llm_model_provider
string | null

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

​
llm_model_name
string | null

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

​
llm_reasoning_effort
enum<string> | null

Per-execution override for reasoning effort on reasoning-capable models.

Available options:
low,
medium,
high,
xhigh
​
source_node_type
enum<string> | null

Surface that created this execution (mirrored to AgentExecutionHistory.source_node_type). Falls back to SourceNodeType.SDK at persist time when unset.

Available options:
workbench,
sdk,
task,
assistant,
webhook,
mcp,
a2a,
telegram,
slack

Response

Successful Response

Task creation response model.

Extends AgentExecution with additional agent_id field.

​
id
string
required
​
agent_id
string
required
​
organization_id
string
required
​
input
AgentExecutionInput · object
required
​
created_at
string<date-time>
required
​
status
enum<string> | null
default:pending
Available options:
pending,
executing,
paused,
error,
failed,
completed,
stopped
​
internal_status
string | null
​
last_executed_node_id
string | null
​
agent_version
string | null
​
started_at
string<date-time> | null
​
paused_at
string<date-time> | null
​
finished_at
string<date-time> | null
​
result
string | null
​
parent_execution
string | null
​
sub_executions
string[] | null
​
finished_sub_executions
string[] | null
​
should_update_parent
boolean | null
default:false
​
is_manually_stopped
boolean | null
default:false
​
is_background
boolean | null
default:false
​
payload_extension
Payload Extension · object
​
hitl_request
HumanInTheLoopRequest · object

Model representing human-in-the-loop approval records for tasks.

Attributes: wait_node_id (str): The id of the node that triggered this HITL.

​
pending_eca_request
PendingECARequest · object
​
source
string | null
​
worker_id
string | null
​
additional_context
string | null
​
instructions_override
string | null
​
expected_output
string | null
​
test_run_node_id
string | null
​
is_orchestration
boolean | null
default:false
​
is_gateway
boolean | null
default:false
​
output_format
enum<string> | null
default:text
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
events_streaming
boolean | null
default:false
​
used_mutating_tools
boolean | null
default:false
​
is_continuous
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null
​
think_mode
enum<string> | null
default:default
Available options:
default,
harder
​
disable_attachment_injection
boolean | null
default:false
​
deep_planning
DeepPlanning · object
​
execution_attempts
integer | null
default:1
​
user_tokens
User Tokens · object
​
user_oidc_token
string | null
​
return_metrics
boolean | null
default:false
​
tokens
LLMTokens · object
​
llm_model_provider
string | null

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

​
llm_model_name
string | null

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

​
llm_reasoning_effort
enum<string> | null

Snapshot of the reasoning effort applied during this execution, when supported by the model.

Available options:
low,
medium,
high,
xhigh