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": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {}
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_format": "text",
  "output_schema": {},
  "run_locally": true,
  "additional_context": "<string>",
  "expected_output": "<string>",
  "events_streaming": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}'

{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {},
      "display_name": "<string>"
    }
  },
  "status": "pending",
  "internal_status": "<string>",
  "last_executed_node_id": "<string>",
  "agent_version": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "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": [
    "<string>"
  ],
  "finished_sub_executions": [
    "<string>"
  ],
  "is_manually_stopped": true,
  "payload_extension": {},
  "hitl_request": {
    "operation_id": "<string>",
    "approved_by": "<string>",
    "rejected_by": "<string>",
    "title": "<string>",
    "description": "<string>",
    "content": "<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": true,
  "used_mutating_tools": true,
  "is_continuous": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}

POST

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": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {}
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_format": "text",
  "output_schema": {},
  "run_locally": true,
  "additional_context": "<string>",
  "expected_output": "<string>",
  "events_streaming": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}'

{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "<string>",
    "files": [
      "<string>"
    ],
    "user": {
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "additional_attributes": {},
      "display_name": "<string>"
    }
  },
  "status": "pending",
  "internal_status": "<string>",
  "last_executed_node_id": "<string>",
  "agent_version": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "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": [
    "<string>"
  ],
  "finished_sub_executions": [
    "<string>"
  ],
  "is_manually_stopped": true,
  "payload_extension": {},
  "hitl_request": {
    "operation_id": "<string>",
    "approved_by": "<string>",
    "rejected_by": "<string>",
    "title": "<string>",
    "description": "<string>",
    "content": "<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": true,
  "used_mutating_tools": true,
  "is_continuous": true,
  "mcp_servers": [
    {}
  ],
  "triggering_agent_id": "<string>",
  "title": "<string>"
}

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

Custom task ID. If not provided, a UUID will be automatically generated. Use this to map tasks to external system IDs.Example: "custom-task-12345"

Response

Returns a complete AgentExecution object with the final result:

string

Unique identifier for the created task (UUID)

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

finished_at

string

ISO 8601 timestamp of when the task finished

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

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "2c126a59-b625-4e4a-a008-cb3eb76cc3b2",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
  "status": "completed",
  "input": {
    "text": "What is 2+2?",
    "files": [],
    "user": null
  },
  "result": "2+2 equals 4",
  "created_at": "2025-11-06T02:47:17.244054Z",
  "started_at": "2025-11-06T02:47:18.100000Z",
  "finished_at": "2025-11-06T02:47:20.500000Z"
}

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

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

API Reference

API v1

Invoke Agent (Sync)

Path Parameters

Request Body

Response

Example Requests

Basic Request

Structured JSON Output

With User Context and Custom Metadata

Markdown Output with Context

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

API Reference

API v1

​Path Parameters

​Request Body

​Response

​Example Requests

​Basic Request

​Structured JSON Output

​With User Context and Custom Metadata

​Markdown Output with Context

​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

Example Response

Notes

See Also