> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke an Agent via API

> Call any xpander agent using a simple HTTP request with curl or any HTTP client.

## Base URL

```text theme={"dark"}
https://api.xpander.ai/v1/agents/{agent_id}/invoke
```

## Authentication

All requests require an API key passed as a header:

```text theme={"dark"}
x-api-key: YOUR_XPANDER_API_KEY
```

<Note>
  `Authorization: Bearer` with an API key is **not** supported. Pass the key as `x-api-key`.
</Note>

## 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 skills authenticated over MCP |

## Examples

### Synchronous Invocation

Waits for the agent to complete and returns the result inline.

```bash theme={"dark"}
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 skills that require OAuth (e.g. Notion, Google Calendar), pass the user's OIDC token:

```bash theme={"dark"}
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"
  }'
```

### Files and images

`input.files` takes URLs alongside the text; the agent receives them as attachments.

```bash theme={"dark"}
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": "Analyze this document",
      "files": ["https://example.com/report.pdf", "https://example.com/chart.png"],
      "user": {"id": "USER_ID", "email": "user@example.com"}
    }
  }'
```

### Asynchronous Invocation

Fire-and-forget - returns immediately with a task ID. Poll for results separately.

```bash theme={"dark"}
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke/async" \
  -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

```json theme={"dark"}
{
  "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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.