Invoke Workflow (Stream)

curl --request POST \
  --url https://api.xpander.ai/v1/workflows/{workflow_id}/invoke/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input": {
    "text": "Draft a post about MCP.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  }
}
'

import requests

url = "https://api.xpander.ai/v1/workflows/{workflow_id}/invoke/stream"

payload = { "input": {
        "text": "Draft a post about MCP.",
        "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: 'Draft a post about MCP.',
      user: {id: 'user-123', email: 'you@example.com'}
    }
  })
};

fetch('https://api.xpander.ai/v1/workflows/{workflow_id}/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/workflows/{workflow_id}/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' => 'Draft a post about MCP.',
        '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/workflows/{workflow_id}/invoke/stream"

	payload := strings.NewReader("{\n  \"input\": {\n    \"text\": \"Draft a post about MCP.\",\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/workflows/{workflow_id}/invoke/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"text\": \"Draft a post about MCP.\",\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/workflows/{workflow_id}/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\": \"Draft a post about MCP.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}"

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

{
  "type": "connected",
  "task_id": "f0f0f0f0-1111-2222-3333-444444444444",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "time": "2026-07-28T21:14:22.053899+00:00"
}

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

POST

workflows

{workflow_id}

invoke

stream

Invoke Workflow (Stream)

curl --request POST \
  --url https://api.xpander.ai/v1/workflows/{workflow_id}/invoke/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input": {
    "text": "Draft a post about MCP.",
    "user": {
      "id": "user-123",
      "email": "you@example.com"
    }
  }
}
'

import requests

url = "https://api.xpander.ai/v1/workflows/{workflow_id}/invoke/stream"

payload = { "input": {
        "text": "Draft a post about MCP.",
        "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: 'Draft a post about MCP.',
      user: {id: 'user-123', email: 'you@example.com'}
    }
  })
};

fetch('https://api.xpander.ai/v1/workflows/{workflow_id}/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/workflows/{workflow_id}/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' => 'Draft a post about MCP.',
        '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/workflows/{workflow_id}/invoke/stream"

	payload := strings.NewReader("{\n  \"input\": {\n    \"text\": \"Draft a post about MCP.\",\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/workflows/{workflow_id}/invoke/stream")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"text\": \"Draft a post about MCP.\",\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/workflows/{workflow_id}/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\": \"Draft a post about MCP.\",\n    \"user\": {\n      \"id\": \"user-123\",\n      \"email\": \"you@example.com\"\n    }\n  }\n}"

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

{
  "type": "connected",
  "task_id": "f0f0f0f0-1111-2222-3333-444444444444",
  "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
  "time": "2026-07-28T21:14:22.053899+00:00"
}

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

Invoke a workflow with real-time streaming via Server-Sent Events (SSE). Receive live updates as the pipeline progresses through each node on the canvas — including tool calls, agent reasoning, sub-agent triggers, and the final result.

Path Parameters

string

required

Workflow ID (UUID)

Query Parameters

string

The workflow version to invoke. Defaults to the latest deployed version.

Request Body

Same as Invoke Workflow (Sync) — see that page for full request body documentation.

Response

Returns a text/event-stream response with Server-Sent Events. Each event contains a JSON payload with task update information. Events are sent as the workflow executes, including status changes, intermediate results, and the final task_finished event.

Example Request

curl -N -X POST "https://api.xpander.ai/v1/workflows/<workflow-id>/invoke/stream" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Generate a comprehensive report"}}'

Notes

The stream ends with a task_finished event
Each SSE event is a data: line containing a JSON object
Use Cache-Control: no-cache and Connection: keep-alive headers for best results
Ideal for building real-time UIs that show pipeline progress across nodes

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

workflow_id

string

required

Query Parameters

version

string | null

The workflow version to invoke. default = latest

Body

application/json

input

AgentExecutionInput · object

required

Show child attributes

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,

email,

api

is_app

boolean | null

default:false

is_steering

boolean | null

default:false

sub_tasks_mode

enum<string> | null

Forces gateway sub-task dispatch: 'sync' runs all downstream sub-tasks inline, 'async' queues them all, 'auto' restores the computed per-sub-task decision.

Available options:

sync,

async,

auto

Response

Successful Response

Overview

REST API - Conversations

REST API - Agents

REST API - Tasks

Agent Workspace

REST API - Knowledge

REST API - Skills

REST API - Workflows

REST API - Custom Functions

REST API - Scheduled Tasks

REST API - Self-Schedules

REST API - Misc

Channels and webhooks

Invoke Workflow (Stream)

Path Parameters

Query Parameters

Request Body

Response

Example Request

Notes

Authorizations

Path Parameters

Query Parameters

Body

Response