Run Gateway Turn (Stream)
curl --request POST \
--url https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"input": {
"text": "",
"files": [],
"user": {
"email": "<string>",
"id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"additional_attributes": {},
"role": "member",
"is_super_admin": false,
"timezone": "<string>"
}
},
"id": "<string>",
"payload_extension": {},
"parent_execution_id": "<string>",
"worker_id": "<string>",
"source": "<string>",
"output_schema": {},
"run_locally": false,
"additional_context": "<string>",
"instructions_override": "<string>",
"test_run_node_id": "<string>",
"expected_output": "<string>",
"events_streaming": false,
"mcp_servers": [],
"triggering_agent_id": "<string>",
"title": "<string>",
"think_mode": "default",
"disable_attachment_injection": false,
"user_tokens": {},
"user_oidc_token": "<string>",
"return_metrics": false,
"llm_model_provider": "<string>",
"llm_model_name": "<string>"
}
'import requests
url = "https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream"
payload = {
"input": {
"text": "",
"files": [],
"user": {
"email": "<string>",
"id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"additional_attributes": {},
"role": "member",
"is_super_admin": False,
"timezone": "<string>"
}
},
"id": "<string>",
"payload_extension": {},
"parent_execution_id": "<string>",
"worker_id": "<string>",
"source": "<string>",
"output_schema": {},
"run_locally": False,
"additional_context": "<string>",
"instructions_override": "<string>",
"test_run_node_id": "<string>",
"expected_output": "<string>",
"events_streaming": False,
"mcp_servers": [],
"triggering_agent_id": "<string>",
"title": "<string>",
"think_mode": "default",
"disable_attachment_injection": False,
"user_tokens": {},
"user_oidc_token": "<string>",
"return_metrics": False,
"llm_model_provider": "<string>",
"llm_model_name": "<string>"
}
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: '',
files: [],
user: {
email: '<string>',
id: '<string>',
first_name: '<string>',
last_name: '<string>',
additional_attributes: {},
role: 'member',
is_super_admin: false,
timezone: '<string>'
}
},
id: '<string>',
payload_extension: {},
parent_execution_id: '<string>',
worker_id: '<string>',
source: '<string>',
output_schema: {},
run_locally: false,
additional_context: '<string>',
instructions_override: '<string>',
test_run_node_id: '<string>',
expected_output: '<string>',
events_streaming: false,
mcp_servers: [],
triggering_agent_id: '<string>',
title: '<string>',
think_mode: 'default',
disable_attachment_injection: false,
user_tokens: {},
user_oidc_token: '<string>',
return_metrics: false,
llm_model_provider: '<string>',
llm_model_name: '<string>'
})
};
fetch('https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream', 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}/gateway/invoke/stream",
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' => '',
'files' => [
],
'user' => [
'email' => '<string>',
'id' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'additional_attributes' => [
],
'role' => 'member',
'is_super_admin' => false,
'timezone' => '<string>'
]
],
'id' => '<string>',
'payload_extension' => [
],
'parent_execution_id' => '<string>',
'worker_id' => '<string>',
'source' => '<string>',
'output_schema' => [
],
'run_locally' => false,
'additional_context' => '<string>',
'instructions_override' => '<string>',
'test_run_node_id' => '<string>',
'expected_output' => '<string>',
'events_streaming' => false,
'mcp_servers' => [
],
'triggering_agent_id' => '<string>',
'title' => '<string>',
'think_mode' => 'default',
'disable_attachment_injection' => false,
'user_tokens' => [
],
'user_oidc_token' => '<string>',
'return_metrics' => false,
'llm_model_provider' => '<string>',
'llm_model_name' => '<string>'
]),
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}/gateway/invoke/stream"
payload := strings.NewReader("{\n \"input\": {\n \"text\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\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}/gateway/invoke/stream")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"input\": {\n \"text\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream")
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\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Run a turn
Run Gateway Turn (Stream)
Run a gateway turn and stream every event over SSE.
POST
/
v1
/
agents
/
{agent_id}
/
gateway
/
invoke
/
stream
Run Gateway Turn (Stream)
curl --request POST \
--url https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"input": {
"text": "",
"files": [],
"user": {
"email": "<string>",
"id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"additional_attributes": {},
"role": "member",
"is_super_admin": false,
"timezone": "<string>"
}
},
"id": "<string>",
"payload_extension": {},
"parent_execution_id": "<string>",
"worker_id": "<string>",
"source": "<string>",
"output_schema": {},
"run_locally": false,
"additional_context": "<string>",
"instructions_override": "<string>",
"test_run_node_id": "<string>",
"expected_output": "<string>",
"events_streaming": false,
"mcp_servers": [],
"triggering_agent_id": "<string>",
"title": "<string>",
"think_mode": "default",
"disable_attachment_injection": false,
"user_tokens": {},
"user_oidc_token": "<string>",
"return_metrics": false,
"llm_model_provider": "<string>",
"llm_model_name": "<string>"
}
'import requests
url = "https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream"
payload = {
"input": {
"text": "",
"files": [],
"user": {
"email": "<string>",
"id": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"additional_attributes": {},
"role": "member",
"is_super_admin": False,
"timezone": "<string>"
}
},
"id": "<string>",
"payload_extension": {},
"parent_execution_id": "<string>",
"worker_id": "<string>",
"source": "<string>",
"output_schema": {},
"run_locally": False,
"additional_context": "<string>",
"instructions_override": "<string>",
"test_run_node_id": "<string>",
"expected_output": "<string>",
"events_streaming": False,
"mcp_servers": [],
"triggering_agent_id": "<string>",
"title": "<string>",
"think_mode": "default",
"disable_attachment_injection": False,
"user_tokens": {},
"user_oidc_token": "<string>",
"return_metrics": False,
"llm_model_provider": "<string>",
"llm_model_name": "<string>"
}
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: '',
files: [],
user: {
email: '<string>',
id: '<string>',
first_name: '<string>',
last_name: '<string>',
additional_attributes: {},
role: 'member',
is_super_admin: false,
timezone: '<string>'
}
},
id: '<string>',
payload_extension: {},
parent_execution_id: '<string>',
worker_id: '<string>',
source: '<string>',
output_schema: {},
run_locally: false,
additional_context: '<string>',
instructions_override: '<string>',
test_run_node_id: '<string>',
expected_output: '<string>',
events_streaming: false,
mcp_servers: [],
triggering_agent_id: '<string>',
title: '<string>',
think_mode: 'default',
disable_attachment_injection: false,
user_tokens: {},
user_oidc_token: '<string>',
return_metrics: false,
llm_model_provider: '<string>',
llm_model_name: '<string>'
})
};
fetch('https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream', 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}/gateway/invoke/stream",
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' => '',
'files' => [
],
'user' => [
'email' => '<string>',
'id' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'additional_attributes' => [
],
'role' => 'member',
'is_super_admin' => false,
'timezone' => '<string>'
]
],
'id' => '<string>',
'payload_extension' => [
],
'parent_execution_id' => '<string>',
'worker_id' => '<string>',
'source' => '<string>',
'output_schema' => [
],
'run_locally' => false,
'additional_context' => '<string>',
'instructions_override' => '<string>',
'test_run_node_id' => '<string>',
'expected_output' => '<string>',
'events_streaming' => false,
'mcp_servers' => [
],
'triggering_agent_id' => '<string>',
'title' => '<string>',
'think_mode' => 'default',
'disable_attachment_injection' => false,
'user_tokens' => [
],
'user_oidc_token' => '<string>',
'return_metrics' => false,
'llm_model_provider' => '<string>',
'llm_model_name' => '<string>'
]),
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}/gateway/invoke/stream"
payload := strings.NewReader("{\n \"input\": {\n \"text\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\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}/gateway/invoke/stream")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"input\": {\n \"text\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.xpander.ai/v1/agents/{agent_id}/gateway/invoke/stream")
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\": \"\",\n \"files\": [],\n \"user\": {\n \"email\": \"<string>\",\n \"id\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"additional_attributes\": {},\n \"role\": \"member\",\n \"is_super_admin\": false,\n \"timezone\": \"<string>\"\n }\n },\n \"id\": \"<string>\",\n \"payload_extension\": {},\n \"parent_execution_id\": \"<string>\",\n \"worker_id\": \"<string>\",\n \"source\": \"<string>\",\n \"output_schema\": {},\n \"run_locally\": false,\n \"additional_context\": \"<string>\",\n \"instructions_override\": \"<string>\",\n \"test_run_node_id\": \"<string>\",\n \"expected_output\": \"<string>\",\n \"events_streaming\": false,\n \"mcp_servers\": [],\n \"triggering_agent_id\": \"<string>\",\n \"title\": \"<string>\",\n \"think_mode\": \"default\",\n \"disable_attachment_injection\": false,\n \"user_tokens\": {},\n \"user_oidc_token\": \"<string>\",\n \"return_metrics\": false,\n \"llm_model_provider\": \"<string>\",\n \"llm_model_name\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Run a turn through the gateway and stream every
TaskUpdateEvent over Server-Sent Events. This is the fast-time-to-first-token path: a connected event flushes immediately, then the router starts answering before any heavy downstream work begins.
Pass id = your conversation_id to start or continue a conversation; omit it to start a new one. Sub-execution events (the downstream agents the router dispatches) are forwarded onto the same stream.
Use the sub_tasks query parameter to force how the router dispatches downstream work: sync runs every sub-execution in the foreground (the turn waits for each child, like the email trigger), async pushes every sub-execution to the background (results are pushed back to the conversation later), and auto restores the computed per-task decision. This is separate from whether this API call blocks, and the mode sticks to the conversation until changed.
See the Agent Gateway overview for the event model and how sub-executions stream back.Authorizations
API Key for authentication
Path Parameters
Query Parameters
Agent version to run.
Force how the gateway dispatches downstream sub-tasks inside this run (not whether this API call blocks): 'sync' runs every sub-task inline, 'async' queues every sub-task, 'auto' restores the computed per-sub-task decision. The mode sticks to the conversation until changed.
Available options:
sync, async, auto Body
application/json
Show child attributes
Show child attributes
Available options:
text, markdown, json, voice Available options:
default, harder Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.
Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.
Per-execution override for reasoning effort on reasoning-capable models.
Available options:
low, medium, high, xhigh Surface that created this execution (mirrored to AgentExecutionHistory.source_node_type). Falls back to SourceNodeType.SDK at persist time when unset.
Available options:
workbench, sdk, task, assistant, webhook, mcp, a2a, telegram, slack Response
Successful Response
Was this page helpful?
⌘I