Skip to main content
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. See the Agent Gateway overview for the event model and how sub-executions stream back.

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Query Parameters

​
version
string | null

Agent version to run.

Body

application/json
​
input
AgentExecutionInput · object
required
​
id
string | null
​
payload_extension
Payload Extension · object | null
​
parent_execution_id
string | null
​
worker_id
string | null
​
source
string | null
​
output_format
enum<string> | null
Available options:
text,
markdown,
json,
voice
​
output_schema
Output Schema · object | null
​
run_locally
boolean | null
default:false
​
additional_context
string | null
​
instructions_override
string | null
​
test_run_node_id
string | null
​
expected_output
string | null
​
events_streaming
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null
​
think_mode
enum<string> | null
default:default
Available options:
default,
harder
​
disable_attachment_injection
boolean | null
default:false
​
user_tokens
User Tokens · object | null
​
user_oidc_token
string | null
​
return_metrics
boolean | null
default:false
​
llm_model_provider
string | null

Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.

​
llm_model_name
string | null

Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.

​
llm_reasoning_effort
enum<string> | null

Per-execution override for reasoning effort on reasoning-capable models.

Available options:
low,
medium,
high,
xhigh
​
source_node_type
enum<string> | null

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