Invoke Agent (Sync)

Execute an agent task synchronously and wait for completion. This endpoint blocks until the task finishes and returns the complete result. Best for tasks expected to complete within 30 seconds.

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

Show Input Object

text

string

The message or task to send to the agent. Either text or files must be provided.

files

array

Array of file URLs or file identifiers to process. Supports documents (PDF, DOCX, TXT), images (JPG, PNG), spreadsheets (CSV, XLSX), and more.Example: ["https://example.com/doc.pdf", "file-id-12345"]

user

object

User information for personalization and audit trail

Show User Object

string

Unique user identifier

first_name

string

User’s first name

last_name

string

User’s last name

string

required

User’s email address (required if user object is provided)

additional_attributes

object

Custom user metadata (e.g., {"customer_tier": "premium", "preferences": {...}})

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"]
}

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"

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).

Response

Returns a complete AgentExecution object with the final result:

string

Unique identifier for the created task (UUID) - this is the thread ID if you provided one

agent_id

string

UUID of the agent that executed this task

organization_id

string

UUID of the organization

status

string

Task execution status: completed, failed, error

input

object

The input object that was provided

result

string

Task execution result content

created_at

string

ISO 8601 timestamp of when the task was created

started_at

string

ISO 8601 timestamp of when execution began (may be null)

finished_at

string

ISO 8601 timestamp of when the task finished

output_format

string

The output format specified in the request

output_schema

object

The output schema if provided in the request

title

string

The task title if provided

source

string

The source identifier (e.g., “api”)

events_streaming

boolean

Whether event streaming was enabled

payload_extension

object

Custom metadata attached to the task

parent_execution

object

Parent task information if this is a sub-task

sub_executions

array

Array of sub-task executions spawned by this task

triggering_agent_id

string

UUID of the agent that triggered this task (if delegated)

Example Requests

Basic Request

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

Structured JSON Output

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Parse this address: 123 Main St, San Francisco, CA 94102"
    },
    "output_format": "json",
    "output_schema": {
      "type": "object",
      "required": ["street", "city", "state", "zip"],
      "properties": {
        "street": {"type": "string"},
        "city": {"type": "string"},
        "state": {"type": "string"},
        "zip": {"type": "string"}
      }
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke

With User Context and Custom Metadata

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Summarize my recent activity",
      "user": {
        "id": "user-456",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@company.com",
        "additional_attributes": {
          "account_type": "enterprise",
          "timezone": "America/Los_Angeles"
        }
      }
    },
    "title": "User Activity Summary",
    "payload_extension": {
      "session_id": "sess-789",
      "source_page": "dashboard"
    }
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke

Markdown Output with Context

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Write a tutorial on REST APIs"
    },
    "output_format": "markdown",
    "additional_context": "Target audience: beginner developers. Include code examples.",
    "expected_output": "A 1000-word tutorial with introduction, examples, and best practices"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke

Multi-Turn Conversation

# 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 Alice and I like Python programming"
    },
    "id": "conversation-thread-123"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke

# Follow-up message - reuses the same ID to maintain context
curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "What is my name and what do I like?"
    },
    "id": "conversation-thread-123"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke
# Agent will respond: "Your name is Alice and you like Python programming"

# Another follow-up in the same 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 in this thread?"
    },
    "id": "conversation-thread-123"
  }' \
  https://api.xpander.ai/v1/agents/{agent_id}/invoke
# Agent will respond based on the full conversation history

Example Response

{
  "id": "test-thread-20251112",
  "agent_id": "efada57d-3d0d-44d1-b64c-e2c2d0dfcc42",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "input": {
    "text": "What is 2+2?",
    "files": [],
    "user": null
  },
  "status": "completed",
  "internal_status": null,
  "last_executed_node_id": null,
  "agent_version": null,
  "created_at": "2025-11-12T06:17:20.631941Z",
  "started_at": null,
  "paused_at": null,
  "finished_at": "2025-11-12T06:17:26.869452Z",
  "result": "2+2 equals 4",
  "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
}

Notes

This endpoint waits for task completion before returning
Recommended timeout: 30-60 seconds
For long-running tasks, use [Invoke Agent (Async)](/API reference/v1/agents/invoke-async) instead
The agent must have deployment_type: serverless or be a running container
Multi-Turn Conversations: Use the same id parameter across requests to maintain conversation context. The agent will remember all previous messages in the thread.

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

Path Parameters

Request Body

Response

Example Requests

Basic Request

Structured JSON Output

With User Context and Custom Metadata

Markdown Output with Context

Multi-Turn Conversation

Example Response

Notes

See Also

Authorizations

Path Parameters

Body

Response

Overview

REST API - Agents

REST API - Tasks

REST API - Knowledge

REST API - Toolkits

REST API - Misc

Python SDK - Core Modules

Python SDK - API Reference

CLI Reference

​Path Parameters

​Request Body

​Response

​Example Requests

​Basic Request

​Structured JSON Output

​With User Context and Custom Metadata

​Markdown Output with Context

​Multi-Turn Conversation

​Example Response

​Notes

​See Also

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Response

Example Requests

Basic Request

Structured JSON Output

With User Context and Custom Metadata

Markdown Output with Context

Multi-Turn Conversation

Example Response

Notes

See Also