Build endpoints

info

The /build endpoints are used by Orbis Studio's frontend visual editor code. These endpoints are part of the internal Orbis Studio codebase.

Don't use these endpoints to run flows in applications that use your Orbis Studio flows. To run flows in your apps, see Flow trigger endpoints.

The /build endpoints support Orbis Studio's frontend code for building flows in the Orbis Studio visual editor. You can use these endpoints to build vertices and flows, as well as execute flows with streaming event responses. You might need to use or understand these endpoints when contributing to the Orbis Studio codebase.

Build flow and stream events

This endpoint builds and executes a flow, returning a job ID that can be used to stream execution events.

1. Send a POST request to the /build/$FLOW_ID/flow endpoint:

   Python

   1import os 2 3import requests 4 5url = f"{os.getenv('LANGFLOW_URL', '')}/api/v1/build/{os.getenv('FLOW_ID', '')}/flow" 6 7headers = { 8 "accept": "application/json", 9 "Content-Type": "application/json", 10 "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}", 11} 12 13payload = {"inputs": {"input_value": "Tell me a story"}} 14 15response = requests.request("POST", url, headers=headers, json=payload) 16response.raise_for_status() 17 18print(response.text) 19

   JavaScript

   1const url = `${process.env.LANGFLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`; 2 3const options = { 4 method: 'POST', 5 headers: { 6 "accept": `application/json`, 7 "Content-Type": `application/json`, 8 "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`, 9 }, 10 body: JSON.stringify({ 11 "inputs": { 12 "input_value": "Tell me a story" 13 } 14}), 15}; 16 17fetch(url, options) 18 .then(async (response) => { 19 if (!response.ok) { 20 throw new Error(`HTTP ${response.status}`); 21 } 22 const text = await response.text(); 23 console.log(text); 24 }) 25 .catch((error) => console.error(error)); 26

   curl

   1curl -X POST \ 2 "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \ 3 -H "accept: application/json" \ 4 -H "Content-Type: application/json" \ 5 -H "x-api-key: $LANGFLOW_API_KEY" \ 6 -d '{ 7 "inputs": { 8 "input_value": "Tell me a story" 9 } 10 }' 11
   Result

   1{ 2 "job_id": "123e4567-e89b-12d3-a456-426614174000" 3} 4

2. After receiving a job ID from the build endpoint, use the /build/$JOB_ID/events endpoint to stream the execution results:

   Python

   1import os 2 3import requests 4 5url = f"{os.getenv('LANGFLOW_URL', '')}/api/v1/build/{os.getenv('JOB_ID', '')}/events" 6 7headers = { 8 "accept": "application/json", 9 "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}", 10} 11 12response = requests.request("GET", url, headers=headers) 13response.raise_for_status() 14 15print(response.text) 16

   JavaScript

   1const url = `${process.env.LANGFLOW_URL ?? ""}/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events`; 2 3const options = { 4 method: 'GET', 5 headers: { 6 "accept": `application/json`, 7 "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`, 8 }, 9}; 10 11fetch(url, options) 12 .then(async (response) => { 13 if (!response.ok) { 14 throw new Error(`HTTP ${response.status}`); 15 } 16 const text = await response.text(); 17 console.log(text); 18 }) 19 .catch((error) => console.error(error)); 20

   curl

   1curl -X GET \ 2 "$LANGFLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events" \ 3 -H "accept: application/json" \ 4 -H "x-api-key: $LANGFLOW_API_KEY" 5
   Result

   1{"event": "vertices_sorted", "data": {"ids": ["ChatInput-XtBLx"], "to_run": ["Prompt-x74Ze", "ChatOutput-ylMzN", "ChatInput-XtBLx", "OpenAIModel-d1wOZ"]}} 2 3{"event": "add_message", "data": {"timestamp": "2025-03-03T17:42:23", "sender": "User", "sender_name": "User", "session_id": "d2bbd92b-187e-4c84-b2d4-5df365704201", "text": "Tell me a story", "files": [], "error": false, "edit": false, "properties": {"text_color": "", "background_color": "", "edited": false, "source": {"id": null, "display_name": null, "source": null}, "icon": "", "allow_markdown": false, "positive_feedback": null, "state": "complete", "targets": []}, "category": "message", "content_blocks": [], "id": "28879bd8-6a68-4dd5-b658-74d643a4dd92", "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201"}} 4 5// ... Additional events as the flow executes ... 6 7{"event": "end", "data": {}} 8

The /build/$FLOW_ID/events endpoint has a stream query parameter that defaults to true. To disable streaming and get all events at once, set ?stream=false.

Python

1import os 2 3import requests 4 5base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "") 6job_id = os.environ.get("JOB_ID", "") 7api_key = os.environ.get("LANGFLOW_API_KEY", "") 8 9# Use the API's `event_delivery` query param to avoid keeping a streaming connection open. 10# For local smoke tests, polling returns a finite JSON response. 11url = f"{base}/api/v1/build/{job_id}/events?event_delivery=polling" 12 13headers = {"accept": "application/json", "x-api-key": api_key} 14 15response = requests.get(url, headers=headers, timeout=60) 16response.raise_for_status() 17 18print(response.text) 19

JavaScript

1const url = `${process.env.LANGFLOW_URL ?? ""}/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false`; 2 3const options = { 4 method: 'GET', 5 headers: { 6 "accept": `application/json`, 7 "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`, 8 }, 9}; 10 11fetch(url, options) 12 .then(async (response) => { 13 if (!response.ok) { 14 throw new Error(`HTTP ${response.status}`); 15 } 16 const text = await response.text(); 17 console.log(text); 18 }) 19 .catch((error) => console.error(error)); 20

curl

1curl -X GET \ 2 "$LANGFLOW_URL/api/v1/build/123e4567-e89b-12d3-a456-426614174000/events?stream=false" \ 3 -H "accept: application/json" \ 4 -H "x-api-key: $LANGFLOW_API_KEY" 5

Build headers

Header	Info	Example
Content-Type	Required. Specifies the JSON format.	"application/json"
accept	Optional. Specifies the response format.	"application/json"
x-api-key	Optional. Required only if authentication is enabled.	"sk-..."

Build parameters

Parameter	Type	Description
inputs	object	Optional. Input values for flow components.
data	object	Optional. Flow data to override stored configuration.
files	array[string]	Optional. List of file paths to use.
start_component_id	string	Optional. ID of the component where the execution should start. Component id values can be found in Orbis Studio JSON files
stop_component_id	string	Optional. ID of the component where the execution should stop. Component id values can be found in Orbis Studio JSON files.
log_builds	Boolean	Whether to record build logs. Default: Enabled (true).

Set start and stop points

The /build endpoint accepts optional values for start_component_id and stop_component_id to control where the flow run starts and stops. Setting stop_component_id for a component triggers the same behavior as clicking Run component on that component in the visual editor: The specified component and all dependent components leading up to that component will run.

The following example stops flow execution at an OpenAI component:

Python

1import os 2 3import requests 4 5url = f"{os.getenv('LANGFLOW_URL', '')}/api/v1/build/{os.getenv('FLOW_ID', '')}/flow" 6 7headers = { 8 "accept": "application/json", 9 "Content-Type": "application/json", 10 "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}", 11} 12 13payload = {"stop_component_id": "OpenAIModel-Uksag"} 14 15response = requests.request("POST", url, headers=headers, json=payload) 16response.raise_for_status() 17 18print(response.text) 19

JavaScript

1const url = `${process.env.LANGFLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`; 2 3const options = { 4 method: 'POST', 5 headers: { 6 "accept": `application/json`, 7 "Content-Type": `application/json`, 8 "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`, 9 }, 10 body: JSON.stringify({ 11 "stop_component_id": "OpenAIModel-Uksag" 12}), 13}; 14 15fetch(url, options) 16 .then(async (response) => { 17 if (!response.ok) { 18 throw new Error(`HTTP ${response.status}`); 19 } 20 const text = await response.text(); 21 console.log(text); 22 }) 23 .catch((error) => console.error(error)); 24

curl

1curl -X POST \ 2 "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \ 3 -H "accept: application/json" \ 4 -H "Content-Type: application/json" \ 5 -H "x-api-key: $LANGFLOW_API_KEY" \ 6 -d '{"stop_component_id": "OpenAIModel-Uksag"}' 7

Override flow parameters

The /build endpoint also accepts inputs for data directly, instead of using the values stored in the Orbis Studio database. This is useful for running flows without having to pass custom values through the visual editor.

Python

1import os 2 3import requests 4 5url = f"{os.getenv('LANGFLOW_URL', '')}/api/v1/build/{os.getenv('FLOW_ID', '')}/flow" 6 7headers = { 8 "accept": "application/json", 9 "Content-Type": "application/json", 10 "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}", 11} 12 13payload = { 14 "data": {"nodes": [], "edges": []}, 15 "inputs": {"input_value": "Your custom input here", "session": "session_id"}, 16} 17 18response = requests.request("POST", url, headers=headers, json=payload) 19response.raise_for_status() 20 21print(response.text) 22

JavaScript

1const url = `${process.env.LANGFLOW_URL ?? ""}/api/v1/build/${process.env.FLOW_ID ?? ""}/flow`; 2 3const options = { 4 method: 'POST', 5 headers: { 6 "accept": `application/json`, 7 "Content-Type": `application/json`, 8 "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`, 9 }, 10 body: JSON.stringify({ 11 "data": { 12 "nodes": [], 13 "edges": [] 14 }, 15 "inputs": { 16 "input_value": "Your custom input here", 17 "session": "session_id" 18 } 19}), 20}; 21 22fetch(url, options) 23 .then(async (response) => { 24 if (!response.ok) { 25 throw new Error(`HTTP ${response.status}`); 26 } 27 const text = await response.text(); 28 console.log(text); 29 }) 30 .catch((error) => console.error(error)); 31

curl

1curl -X POST \ 2 "$LANGFLOW_URL/api/v1/build/$FLOW_ID/flow" \ 3 -H "accept: application/json" \ 4 -H "Content-Type: application/json" \ 5 -H "x-api-key: $LANGFLOW_API_KEY" \ 6 -d '{ 7 "data": { 8 "nodes": [], 9 "edges": [] 10 }, 11 "inputs": { 12 "input_value": "Your custom input here", 13 "session": "session_id" 14 } 15 }' 16

Result

1{ "job_id": "0bcc7f23-40b4-4bfa-9b8a-a44181fd1175" } 2

See also

• Get Vertex builds
• Delete Vertex builds
• Session ID