Skip to main content
The Unified API lets you invoke any xpander agent from your application with a single HTTP request. All agents—regardless of framework—use the same endpoint and request format.

​
When to use the API

Use the Unified API when you want to:
  • Embed agent capabilities directly into your product
  • Trigger agents from backend services or serverless functions
  • Build custom interfaces beyond Slack, MCP, or the Web UI
  • Orchestrate agents as part of a larger workflow

​
Basic usage

curl --request POST \
  --url https://api.xpander.ai/v1/agents/<agent-id>/invoke \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
    "input": {
      "text": "Summarize the latest sales report"
    }
  }'
The response includes the agent’s output along with metadata about the task execution.

​
Multimodal inputs

All API requests support multimodal inputs. You can pass text, files, and images in the same request: 
curl --request POST \
  --url https://api.xpander.ai/v1/agents/<agent-id>/invoke \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your-api-key>' \
  --data '{
    "input": {
      "text": "Analyze this document",
      "files": ["https://example.com/report.pdf"],
      "images": ["https://example.com/chart.png"]
    }
  }'
The platform automatically converts inputs to the format your agent’s framework expects.

​
Sync vs async

The API supports both synchronous and asynchronous invocation:
  • Sync (/invoke): Waits for the agent to complete and returns the result. Best for quick tasks.
  • Async (/invoke/async): Returns immediately with a task ID. Poll for results or use webhooks. Best for long-running tasks.

​
Authentication

Every request requires an API key in the x-api-key header. Generate keys in the xpander dashboard under Settings > API Keys.

​
Next steps

For complete endpoint documentation, request/response schemas, and error codes, see the API Reference.