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 @- <<EOF
{
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  }
}
EOF

import requests

url = "https://api.xpander.ai/v1/agents/{agent_id}/invoke"

payload = { "input": {
        "text": "Summarize today's signups.",
        "user": {
            "id": "user-123",
            "email": "you@example.com"
        }
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {
      text: 'Summarize today\'s signups.',
      user: {id: 'user-123', email: 'you@example.com'}
    }
  })
};

fetch('https://api.xpander.ai/v1/agents/{agent_id}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents/{agent_id}/invoke",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        'text' => 'Summarize today\'s signups.',
        'user' => [
                'id' => 'user-123',
                'email' => 'you@example.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents/{agent_id}/invoke"

	payload := strings.NewReader("{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/agents/{agent_id}/invoke")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents/{agent_id}/invoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "f0f0f0f0-1111-2222-3333-444444444444",
  "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "status": "completed",
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  },
  "result": "42 new signups today, up 12% week over week.",
  "created_at": "2026-07-28T20:59:02.915959Z",
  "finished_at": "2026-07-28T20:59:51.661537Z",
  "llm_model_provider": "anthropic",
  "llm_model_name": "claude-sonnet-5",
  "tokens": {
    "input_tokens": 70216,
    "output_tokens": 3496,
    "total_tokens": 73712
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<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 @- <<EOF
{
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  }
}
EOF

import requests

url = "https://api.xpander.ai/v1/agents/{agent_id}/invoke"

payload = { "input": {
        "text": "Summarize today's signups.",
        "user": {
            "id": "user-123",
            "email": "you@example.com"
        }
    } }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {
      text: 'Summarize today\'s signups.',
      user: {id: 'user-123', email: 'you@example.com'}
    }
  })
};

fetch('https://api.xpander.ai/v1/agents/{agent_id}/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents/{agent_id}/invoke",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'input' => [
        'text' => 'Summarize today\'s signups.',
        'user' => [
                'id' => 'user-123',
                'email' => 'you@example.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents/{agent_id}/invoke"

	payload := strings.NewReader("{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/agents/{agent_id}/invoke")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents/{agent_id}/invoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {\n    \"text\": \"Summarize today's signups.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "f0f0f0f0-1111-2222-3333-444444444444",
  "agent_id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "status": "completed",
  "input": {
    "text": "Summarize today's signups.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  },
  "result": "42 new signups today, up 12% week over week.",
  "created_at": "2026-07-28T20:59:02.915959Z",
  "finished_at": "2026-07-28T20:59:51.661537Z",
  "llm_model_provider": "anthropic",
  "llm_model_name": "claude-sonnet-5",
  "tokens": {
    "input_tokens": 70216,
    "output_tokens": 3496,
    "total_tokens": 73712
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Invoke an agent synchronously. The request blocks until the agent finishes (typically 5–30 seconds) and returns the completed task with the result. For longer-running tasks, use Invoke Agent (Async) or Invoke Agent (Stream).

Path Parameters

string

required

Agent ID (UUID)

Request Body

Only input is required, with the prompt in input.text. input.user is optional. When you send it, input.user.email is required. user_oidc_token is optional and is used by skills that sign in with MCP OAuth.

object

required

Show Input Object

string

required

The message or prompt to send to the agent.

object

Identity of the end user invoking the agent.

Show User Object

string

External user ID from your system.

string

required

User email address.

string

Optional OIDC token for MCP OAuth-authenticated tools. An MCP skill set to Signed-in user (SSO) does not read this field: on an API call it uses the stored SSO sign-in of the agent’s default user.

string

Thread ID for multi-turn conversations. Pass the id from a previous task’s response to continue the same conversation. The agent will have full context of all prior messages. If omitted, a new thread is created automatically.

boolean

default:"false"

When true, files passed in input.files are not injected into the LLM context window. The file URLs are still available to the agent’s tools, but the raw content won’t be prepended to the prompt.Use this when:

Files are large (would exceed the model’s context limit)
You want tools to process the files rather than the LLM reading them directly
You’re passing many files and don’t need them all in context

Default (false): file contents are downloaded, extracted, and injected directly into the LLM prompt as context.

string

default:"default"

Controls the agent’s reasoning depth. default for standard reasoning, harder for deeper chain-of-thought analysis. Use harder for complex multi-step tasks that benefit from more deliberate planning.

string

Additional instructions appended to the agent’s system prompt for this invocation only. Use this to adjust behavior per-request without changing the agent’s configuration — for example, restricting output format, adding constraints, or changing tone.

string

Extra context appended to the agent’s system prompt for this invocation only. Unlike instructions_override (which adds behavioral instructions), this supplies supplementary facts or context the agent should consider for this run — e.g. relevant background data, the current state of an external system, or a user’s recent activity.

string

Natural-language description of the desired output (e.g., "A bulleted list of key findings"). Guides the agent’s response style.

string

Per-execution LLM provider override. Use the provider’s internal identifier (e.g. openai, anthropic, bedrock) from GET /v1/misc/llm_providers. Omit to use the agent’s configured provider.

string

Per-execution model override. Must be a valid model under the chosen provider (GET /v1/misc/llm_providers/{provider_identifier}/models). Examples: claude-sonnet-4-6, gpt-5, gemini-2.0-flash. Omit to use the agent’s configured model.

string

Per-execution reasoning-effort override for reasoning-capable models (e.g. GPT-5). One of low, medium, high, xhigh. Omit to use the agent’s configured reasoning effort.

Query Parameters

string

Agent version to invoke. Defaults to the latest deployed version. Use "draft" to test undeployed changes.

Response

The response is the full task object. The key fields you’ll use:

string

Task/thread ID. Pass this back as id in your next request to continue the conversation.

string

completed, failed, error, or stopped

string

The agent’s response. If output_format is json, this is a JSON string — parse it with JSON.parse() or jq.

string

ISO 8601 timestamp when the task was created

string

ISO 8601 timestamp when the task completed

string

The provider override sent with this request, or null when you did not override it.

string

The model name override sent with this request, or null when you did not override it.

string

The reasoning effort override sent with this request, or null when you did not override it.

Simplest Possible Invoke

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "What is xpander.ai?"}}'

Extract just the result:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "What is xpander.ai?"}}' | jq -r '.result'

Multi-Turn Conversation

Pass the id from the first response to continue the thread:

# Turn 1
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Hi, my name is David and I work at xpander.ai"}}'

# Response includes: "id": "6525177e-06a1-4063-82fe-37382d2302a5"

# Turn 2 — pass the same id
curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "What is my name and where do I work?"},
    "id": "6525177e-06a1-4063-82fe-37382d2302a5"
  }'

# Agent responds: "Your name is David and you work at xpander.ai."

The agent remembers all previous messages in the thread. Always reuse the same id for follow-ups.

With User Identity

Pass the user’s identity so the agent can personalize responses and use identity-aware skills:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What is my user ID and email?",
      "user": {
        "id": "user-123",
        "email": "david@xpander.ai"
      }
    }
  }'

{
  "status": "completed",
  "result": "Your user ID is user-123 and your email is david@xpander.ai."
}

The agent sees the user object as context. When you send user, email is required and id is optional.

With MCP OAuth

Pass user_oidc_token when the agent uses MCP skills that sign in with OAuth on behalf of the user:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "Create a calendar event for tomorrow at 10am",
      "user": {
        "id": "user-123",
        "email": "david@xpander.ai"
      }
    },
    "user_oidc_token": "USER_OIDC_TOKEN"
  }'

Processing Files

Files passed in input.files are downloaded and injected directly into the LLM context window by default. This works well for small-to-medium files:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What is the abstract of this paper?",
      "files": ["https://assets.xpanderai.io/static/pdf/bitcoin.pdf"]
    }
  }'

{
  "status": "completed",
  "result": "The abstract describes a peer-to-peer electronic cash system that enables direct online payments without financial institutions, solving the double-spending problem through a distributed network using proof-of-work and cryptographic signatures."
}

The 9-page Bitcoin whitepaper (above) processes successfully. Its content fits within the model’s context window.

Large Files

A large file is still accepted. This request sends a 185-page PDF, and the agent answers correctly:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "What year was the Apple Macintosh introduced?",
      "files": ["https://assets.xpanderai.io/static/pdf/Introducing_the_Apple_Macintosh_1984.pdf"]
    }
  }'

{
  "status": "completed",
  "result": "The Apple Macintosh was introduced in **1984**."
}

Every file you inject uses part of the model’s context window, on every turn of the thread. For large documents, or documents you query often, use a Knowledge Base. Add the document to a knowledge base and attach it to the agent. The agent then searches it when it needs to.

Disable Context Injection

Set disable_attachment_injection: true to pass the file URL to the agent’s tools without injecting its content into the LLM prompt:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {
      "text": "Analyze this dataset",
      "files": ["https://example.com/data.csv"]
    },
    "disable_attachment_injection": true
  }'

With this flag, the file URL is available to the agent’s tools but the raw content is not prepended to the prompt. Use this when you want the agent’s tools to process the file rather than the LLM reading it directly.

Per-Request Instruction Override

Append instructions for this specific invocation without changing the agent’s configuration:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "What is a webhook?"},
    "title": "Webhook question",
    "instructions_override": "Always respond in exactly 2 sentences. Never use emojis."
  }'

{
  "status": "completed",
  "title": "Webhook question",
  "result": "A webhook is an HTTP request that one system sends to another when an event happens. The receiving system reads the request and acts on it right away."
}

Per-Execution LLM Override

Override the agent’s configured provider, model, or reasoning effort for a single invocation without mutating the agent. Useful for A/B testing models, routing specific requests to a stronger or cheaper model, or dialing up reasoning effort on complex prompts:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "Summarize the attached research paper"},
    "llm_model_provider": "openai",
    "llm_model_name": "gpt-5",
    "llm_reasoning_effort": "high"
  }'

All three fields are optional and independent. Supply only the ones you want to override. Omitted fields fall back to the agent’s configured values. The response echoes the override in llm_model_provider, llm_model_name and llm_reasoning_effort. A field you did not override is null in the response, and the agent’s configured value applies.

Structured JSON Output

Request structured output with a JSON Schema:

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "input": {"text": "Look up Stripe"},
    "output_format": "json",
    "output_schema": {
      "type": "object",
      "properties": {"company": {"type": "string"}, "founded": {"type": "integer"}, "summary": {"type": "string"}},
      "required": ["company", "summary"],
      "additionalProperties": false
    }
  }'

The per-call schema applies to runs the API starts directly; a turn inside an agent’s conversation uses the agent-level schema.

To configure output_format and output_schema on the agent itself, use the Update Agent endpoint or configure it in the dashboard under the Output tab.

Example Response

{
  "id": "6525177e-06a1-4063-82fe-37382d2302a5",
  "agent_id": "<agent-id>",
  "organization_id": "<org-id>",
  "status": "completed",
  "input": {
    "text": "What is xpander.ai in one sentence?"
  },
  "result": "xpander.ai is a full-stack platform for building, deploying, and running autonomous AI agents in production.",
  "source": "api",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "created_at": "2026-02-07T10:15:22.100233Z",
  "started_at": "2026-02-07T10:15:22.500000Z",
  "finished_at": "2026-02-07T10:15:28.997811Z",
  "execution_attempts": 1,
  "llm_model_provider": null,
  "llm_model_name": null,
  "llm_reasoning_effort": null
}

​Path Parameters

​Request Body

​Query Parameters

​Response

​Simplest Possible Invoke

​Multi-Turn Conversation

​With User Identity

​With MCP OAuth

​Processing Files

​Large Files

​Disable Context Injection

​Per-Request Instruction Override

​Per-Execution LLM Override

​Structured JSON Output

​Example Response

​See Also

Authorizations

Path Parameters

Query Parameters

Body

Response

Path Parameters

Request Body

Query Parameters

Response

Simplest Possible Invoke

Multi-Turn Conversation

With User Identity

With MCP OAuth

Processing Files

Large Files

Disable Context Injection

Per-Request Instruction Override

Per-Execution LLM Override

Structured JSON Output

Example Response

See Also