Base URL
https://api.xpander.ai/v1/agents/{agent_id}/invoke
Authentication
All requests require an API key passed as a header:
x-api-key: YOUR_XPANDER_API_KEY
Authorization: Bearer is not supported. Use x-api-key only.
Request Body
| Field | Type | Required | Description |
|---|
input.text | string | ✅ | The prompt to send to the agent |
input.user.id | string | ✅ | The xpander user ID |
input.user.email | string | ✅ | The user’s email address |
user_oidc_token | string | ⬜ | OAuth token for MCP-authenticated tools |
Examples
Synchronous Invocation
Waits for the agent to complete and returns the result inline.
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_XPANDER_API_KEY" \
-d '{
"input": {
"text": "Your prompt here",
"user": {
"id": "USER_ID",
"email": "user@example.com"
}
}
}'
With MCP OAuth Token
If the agent uses tools that require OAuth (e.g. Notion, Google Calendar), pass the user’s OIDC token:
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_XPANDER_API_KEY" \
-d '{
"input": {
"text": "Your prompt here",
"user": {
"id": "USER_ID",
"email": "user@example.com"
}
},
"user_oidc_token": "USER_OAUTH_TOKEN"
}'
Asynchronous Invocation
Fire-and-forget — returns immediately with a task ID. Poll for results separately.
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke?asynchronous=true" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_XPANDER_API_KEY" \
-d '{
"input": {
"text": "Your prompt here",
"user": {
"id": "USER_ID",
"email": "user@example.com"
}
}
}'
Response
{
"id": "task-uuid",
"agent_id": "agent-uuid",
"status": "completed",
"result": "Agent response here",
"source": "api",
"created_at": "2026-04-10T17:34:09.655630Z",
"finished_at": "2026-04-10T17:34:18.685730Z"
}
Status values
| Status | Meaning |
|---|
pending | Task queued |
executing | Agent is running |
completed | Finished successfully |
error | Failed — check result for details |
What NOT to Use
| ❌ Doesn’t work | ✅ Use instead |
|---|
Authorization: Bearer <key> | x-api-key: <key> |
webhook.xpander.ai (wraps body as string) | api.xpander.ai/v1/agents/{id}/invoke |
input.user with only id | Include both id and email |
