> ## 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` is **not** supported. Use `x-api-key` only.
</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 MCP-authenticated tools |

## 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 tools 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"
  }'
```

### 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?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

```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`          |