Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
invoke
/
async
Invoke Agent (Async)
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/invoke/async \
  --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": {}
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_format": "text",
  "output_schema": {},
  "run_locally": false,
  "additional_context": "<string>",
  "expected_output": "<string>",
  "events_streaming": false,
  "mcp_servers": [],
  "triggering_agent_id": "<string>",
  "title": "<string>",
  "think_mode": "default",
  "disable_attachment_injection": false
}
'
{
  "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": {}
    }
  },
  "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": [],
  "is_manually_stopped": false,
  "payload_extension": {},
  "hitl_request": {
    "operation_id": "<string>",
    "content": "<string>",
    "approved_by": "<string>",
    "rejected_by": "<string>",
    "title": "<string>",
    "description": "<string>"
  },
  "pending_eca_request": {
    "connector_name": "<string>",
    "auth_url": "<string>"
  },
  "source": "<string>",
  "worker_id": "<string>",
  "additional_context": "<string>",
  "expected_output": "<string>",
  "output_format": "text",
  "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
}
Execute an agent task asynchronously. This endpoint returns immediately with a task ID that can be used to poll for results. Best for long-running tasks or when you need non-blocking execution.

​
Path Parameters

​
agent_id
string
required
Unique identifier of the agent to invoke (UUID format)

​
Request Body

​
input
object
required
Agent execution input containing the task details
​
output_format
string
Desired output format. Valid values: text | json | markdownDefault: text
  • text: Plain text response
  • json: Structured JSON output (use with output_schema for validation)
  • markdown: Formatted markdown response
​
output_schema
object
JSON Schema to validate and structure the agent’s output. When provided with output_format: "json", the agent will return data conforming to this schema.Example:
{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string", "format": "email"}
  }
}
​
additional_context
string
Additional context to guide the agent’s behavior. Use this to specify tone, audience, constraints, or background information.Example: "This is for executive leadership. Use professional tone and focus on business impact."
​
expected_output
string
Description of the expected output format, length, or structure. Helps guide the agent to produce the desired result.Example: "A 500-word summary with 3 key recommendations and supporting data."
​
title
string
Human-readable title for the task. Useful for identification and organization in task lists.Example: "Q4 Sales Analysis"
​
parent_execution_id
string
UUID of the parent task if this is a sub-task. Used for multi-agent workflows and task hierarchies.Example: "550e8400-e29b-41d4-a716-446655440000"
​
triggering_agent_id
string
UUID of the agent that triggered this task. Used for tracking agent-to-agent delegation.Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
​
payload_extension
object
Custom metadata to attach to the task. Any valid JSON object. Useful for tracking, routing, or application-specific data.Example:
{
  "request_id": "REQ-2025-001",
  "priority": "high",
  "department": "sales",
  "tags": ["urgent", "vip-customer"]
}
​
events_streaming
boolean
Enable detailed event streaming for progress tracking. When true, provides granular events about tool calls and execution steps.Default: falseNote: Only effective when using the /invoke/stream endpoint.
​
mcp_servers
array
Array of Model Context Protocol (MCP) server configurations to use during execution. Enables integration with external tools and services.Example:
[
  {
    "name": "web-search",
    "config": {"provider": "google", "max_results": 10}
  }
]
​
source
string
Identifier for the source system or application that created this task. Useful for analytics and debugging.Example: "mobile-app" | "web-dashboard" | "api-integration"
​
user_tokens
object
User-specific authentication tokens for MCP servers with OAuth authentication. Allows passing pre-authenticated tokens to bypass the interactive OAuth flow during agent execution.The object maps MCP graph item IDs to their corresponding access tokens. To get the graph item IDs for your agent’s MCP servers, use the Get Agent endpoint and inspect the graph.items array for items with type: "mcp".Example:
{
  "mcp-graph-item-uuid-1": "user-access-token-abc123",
  "mcp-graph-item-uuid-2": "user-access-token-xyz789"
}
When to use: If your agent uses MCP servers with OAuth authentication, you can pre-authenticate users through your own OAuth flow and pass their tokens here to avoid the interactive login prompt during execution.
​
id
string
Thread ID for conversation context. This ID is critical for multi-turn conversations:
  • If not provided: A UUID will be automatically generated (recommended for single-turn requests)
  • First message in conversation: Provide a unique UUID and save it for subsequent messages
  • Follow-up messages: Use the same id from the first request to maintain conversation history
  • The agent will remember all previous messages in the thread when you reuse the same ID
Example: "a37db9a1-e483-4544-9136-b32120ae8c81"
Multi-Turn Conversations: To enable the agent to remember previous messages, always use the same id for all requests in a conversation thread. Each unique id represents a separate conversation session. The response will include the same id (whether you provided it or it was auto-generated).
​
worker_id
string
Identifier for the worker or process handling this task. Used for distributed execution tracking.
​
run_locally
boolean
Execute the task locally instead of in the cloud. Used for development and testing.Default: false

​
Response

Returns a complete AgentExecution object:
​
id
string
Unique identifier for the created task (UUID) - use this to poll for results
​
agent_id
string
UUID of the agent executing this task
​
organization_id
string
UUID of the organization
​
status
string
Initial task status: pending, executing, completed, failed
​
input
object
The input object that was provided
​
created_at
string
ISO 8601 timestamp of when the task was created
​
result
string
Task result (null until completed)
​
output_format
string
The output format specified
​
output_schema
object
The output schema if provided

​
Example Requests

​
Basic Request

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "What is the weather in San Francisco?"
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Structured JSON Output

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Extract contact info: John Doe, john@example.com, (555) 123-4567"
    },
    "output_format": "json",
    "output_schema": {
      "type": "object",
      "required": ["name", "email", "phone"],
      "properties": {
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "phone": {"type": "string"}
      }
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
File Processing with User Context

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Analyze these documents and summarize key findings",
      "files": [
        "https://example.com/report.pdf",
        "https://example.com/data.csv"
      ],
      "user": {
        "id": "user-123",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@company.com",
        "additional_attributes": {
          "department": "analytics",
          "role": "senior_analyst"
        }
      }
    },
    "title": "Q4 Report Analysis",
    "additional_context": "Focus on year-over-year trends and regional performance",
    "expected_output": "Executive summary with 3-5 key insights"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Multi-Agent Workflow

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Process this sub-task"
    },
    "parent_execution_id": "parent-task-uuid",
    "triggering_agent_id": "coordinator-agent-uuid",
    "payload_extension": {
      "workflow_id": "WF-2025-001",
      "step": 2,
      "total_steps": 5
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
Advanced: Full Feature Set

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Research AI trends and create a presentation",
      "files": [],
      "user": {
        "id": "analyst-001",
        "email": "analyst@company.com"
      }
    },
    "output_format": "markdown",
    "title": "AI Trends Research",
    "additional_context": "Target audience: C-level executives. Professional tone.",
    "expected_output": "10-slide presentation outline with key points",
    "payload_extension": {
      "project_id": "PROJ-2025-042",
      "priority": "high",
      "deadline": "2025-11-15"
    },
    "mcp_servers": [
      {
        "name": "web-search",
        "config": {"provider": "google"}
      }
    ],
    "source": "research-portal"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

​
With MCP OAuth Authentication (user_tokens)

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Analyze my Slack workspace activity",
      "user": {
        "id": "user-456",
        "email": "user@company.com"
      }
    },
    "user_tokens": {
      "mcp-graph-item-uuid-slack": "xoxp-slack-user-token",
      "mcp-graph-item-uuid-github": "ghp_github-user-token"
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async
How to get MCP graph item IDs: Call GET /v1/agents/ and inspect graph.items for entries with type: "mcp".

​
Multi-Turn Conversation (Async)

# First message - creates a new conversation thread
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "My name is Bob and I work in sales"
    },
    "id": "thread-async-456"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async

# Poll for completion using the task ID, then send follow-up
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "What is my name and what department do I work in?"
    },
    "id": "thread-async-456"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async
# Agent will remember: "Your name is Bob and you work in sales"

# Another follow-up in the same conversation thread
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "How many messages have I sent you in this thread?"
    },
    "id": "thread-async-456"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke/async
# Agent will respond based on full conversation history

​
Example Response

{
  "id": "60ce6693-9c4d-45a0-a675-76cd8cbefbac",
  "agent_id": "e9aaf26b-5e8b-42ce-9a96-b32acd9136cb",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "input": {
    "text": "What is 5+5?",
    "files": [],
    "user": null
  },
  "status": "pending",
  "internal_status": null,
  "last_executed_node_id": null,
  "agent_version": null,
  "created_at": "2025-11-06T21:08:55.503495Z",
  "started_at": null,
  "paused_at": null,
  "finished_at": null,
  "result": null,
  "parent_execution": null,
  "sub_executions": [],
  "finished_sub_executions": [],
  "is_manually_stopped": false,
  "payload_extension": null,
  "hitl_request": null,
  "pending_eca_request": null,
  "source": "api",
  "worker_id": null,
  "additional_context": null,
  "expected_output": null,
  "output_format": "text",
  "output_schema": null,
  "events_streaming": false,
  "used_mutating_tools": false,
  "is_continuous": false,
  "mcp_servers": [],
  "triggering_agent_id": null,
  "title": null
}

​
Polling for Results

Use the task ID with the [Get Task](/API reference/v1/tasks/get-task) endpoint to check status and retrieve results: 
# Poll for results (repeat until status is "completed")
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.xpander.ai/v1/tasks/{task_id}

​
Notes

  • Multi-Turn Conversations: Use the same id parameter across requests to maintain conversation context. The agent will remember all previous messages in the thread.
  • Each task returns immediately with a task ID - poll the /tasks/{task_id} endpoint to check completion status
  • For multi-turn conversations, wait for each task to complete before sending the next message to ensure proper context

​
See Also

  • [Invoke Agent (Sync)](/API reference/v1/agents/invoke-sync) - For quick tasks that complete in under 30 seconds
  • [Invoke Agent (Stream)](/API reference/v1/agents/invoke-stream) - For real-time streaming responses
  • [Get Task](/API reference/v1/tasks/get-task) - Poll for task status and retrieve results
  • [Get Task Thread](/API reference/v1/tasks/get-thread) - View complete conversation history for a thread
  • [List Tasks](/API reference/v1/tasks/list-tasks) - Query and filter task history
  • [Get Agent Tasks](/API reference/v1/agents/list-agents) - Get all tasks for a specific agent
  • Agent Memory - Configure how agents store and recall conversation history

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

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
default:text
Available options:
text,
markdown,
json
​
output_schema
Output Schema · object
​
run_locally
boolean | null
default:false
​
additional_context
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

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
​
is_manually_stopped
boolean | null
default:false
​
payload_extension
Payload Extension · object
​
hitl_request
HumanInTheLoop · object
​
pending_eca_request
PendingECARequest · object
​
source
string | null
​
worker_id
string | null
​
additional_context
string | null
​
expected_output
string | null
​
output_format
enum<string> | null
default:text
Available options:
text,
markdown,
json
​
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