Skip to content

docs: pass env var to run command and endpoint as header #11447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mendonk wants to merge 3 commits into
base: docs-1.8-release
Choose a base branch
from
Open

docs: pass env var to run command and endpoint as header #11447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b091aeb
pass-env-var-to-lfx
mendonk Jan 26, 2026
3b4a3b7
add-env-var-passing-to-run-endpoint
mendonk Jan 26, 2026
5d8789f
add-python-and-js-commands
mendonk Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
333 changes: 329 additions & 4 deletions docs/docs/API-Reference/api-flows-run.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ title: Flow trigger endpoints
slug: /api-flows-run
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Use the `/run` and `/webhook` endpoints to run flows.

To create, read, update, and delete flows, see [Flow management endpoints](/api-flows).
Expand All @@ -20,6 +23,67 @@ Flow IDs can be found on the code snippets on the [**API access** pane](/concept
The following example runs the **Basic Prompting** template flow with flow parameters passed in the request body.
This flow requires a chat input string (`input_value`), and uses default values for all other parameters.

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID"

# Request payload
payload = {
"input_value": "Tell me about something interesting!",
"session_id": "chat-123",
"input_type": "chat",
"output_type": "chat",
"output_component": ""
}

# Request headers
headers = {
"Content-Type": "application/json",
"x-api-key": "LANGFLOW_API_KEY"
}

try:
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
print(response.json())
except requests.exceptions.RequestException as e:
print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
input_value: "Tell me about something interesting!",
session_id: "chat-123",
input_type: "chat",
output_type: "chat",
output_component: ""
};

const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'LANGFLOW_API_KEY'
},
body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID', options)
.then(response => response.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
"$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
Expand All @@ -30,11 +94,13 @@ curl -X POST \
"session_id": "chat-123",
"input_type": "chat",
"output_type": "chat",
"output_component": "",
"tweaks": null
"output_component": ""
}'
```

</TabItem>
</Tabs>

The response from `/v1/run/$FLOW_ID` includes metadata, inputs, and outputs for the run.

<details>
Expand Down Expand Up @@ -84,6 +150,77 @@ With `/v1/run/$FLOW_ID`, the flow is executed as a batch with optional LLM token

To stream LLM token responses, append the `?stream=true` query parameter to the request:

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true"

# Request payload
payload = {
"message": "Tell me something interesting!",
"session_id": "chat-123"
}

# Request headers
headers = {
"accept": "application/json",
"Content-Type": "application/json",
"x-api-key": "LANGFLOW_API_KEY"
}

try:
response = requests.post(url, json=payload, headers=headers, stream=True)
response.raise_for_status()

# Process streaming response
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))
except requests.exceptions.RequestException as e:
print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
message: "Tell me something interesting!",
session_id: "chat-123"
};

const options = {
method: 'POST',
headers: {
'accept': 'application/json',
'Content-Type': 'application/json',
'x-api-key': 'LANGFLOW_API_KEY'
},
body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true', options)
.then(async response => {
const reader = response.body?.getReader();
const decoder = new TextDecoder();

if (reader) {
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
}
})
.catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
"$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
Expand All @@ -96,6 +233,9 @@ curl -X POST \
}'
```

</TabItem>
</Tabs>

LLM chat responses are streamed back as `token` events, culminating in a final `end` event that closes the connection.

<details>
Expand Down Expand Up @@ -132,8 +272,9 @@ The following example is truncated to illustrate a series of `token` events as w
| 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-..." |
| accept | Optional. Specifies the response format. Defaults to JSON if not specified. | "application/json" |
| x-api-key | Required. Your Langflow API key for authentication. Can be passed as a header or query parameter. | "sk-..." |
| `X-LANGFLOW-GLOBAL-VAR-*` | Optional. Pass global variables to the flow. Variable names are automatically converted to uppercase. These variables take precedence over OS environment variables and are only available during this specific request execution. | `"X-LANGFLOW-GLOBAL-VAR-API_KEY: sk-..."` |

### Run endpoint parameters

Expand All @@ -150,6 +291,93 @@ The following example is truncated to illustrate a series of `token` events as w

### Request example with all headers and parameters

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true"

# Request payload with tweaks
payload = {
"input_value": "Tell me a story",
"input_type": "chat",
"output_type": "chat",
"output_component": "chat_output",
"session_id": "chat-123",
"tweaks": {
"component_id": {
"parameter_name": "value"
}
}
}

# Request headers
headers = {
"Content-Type": "application/json",
"accept": "application/json",
"x-api-key": "LANGFLOW_API_KEY"
}

try:
response = requests.post(url, json=payload, headers=headers, stream=True)
response.raise_for_status()

# Process streaming response
for line in response.iter_lines():
if line:
print(line.decode('utf-8'))
except requests.exceptions.RequestException as e:
print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
input_value: "Tell me a story",
input_type: "chat",
output_type: "chat",
output_component: "chat_output",
session_id: "chat-123",
tweaks: {
component_id: {
parameter_name: "value"
}
}
};

const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'accept': 'application/json',
'x-api-key': 'LANGFLOW_API_KEY'
},
body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true', options)
.then(async response => {
const reader = response.body?.getReader();
const decoder = new TextDecoder();

if (reader) {
while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
}
})
.catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
"$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
Expand All @@ -170,6 +398,103 @@ curl -X POST \
}'
```

</TabItem>
</Tabs>

### Pass global variables in request headers {#pass-global-variables-in-headers}

You can pass global variables to your flow using HTTP headers with the format `X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME}`.

Variables passed in headers take precedence over OS environment variables. If a variable is provided in both a header and an environment variable, the header value is used. Variables are only available during this specific request execution and aren't persisted.

Variable names are automatically converted to uppercase. For example, `X-LANGFLOW-GLOBAL-VAR-api-key` becomes `API_KEY` in your flow.

You don't need to create these variables in Langflow's Global Variables section first. Pass any variable name using this header format.

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID"

# Request payload
payload = {
"input_value": "Tell me about something interesting!",
"input_type": "chat",
"output_type": "chat"
}

# Request headers with global variables
headers = {
"Content-Type": "application/json",
"x-api-key": "LANGFLOW_API_KEY",
"X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY": "sk-...",
"X-LANGFLOW-GLOBAL-VAR-USER_ID": "user123",
"X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT": "production"
}

try:
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
print(response.json())
except requests.exceptions.RequestException as e:
print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
input_value: "Tell me about something interesting!",
input_type: "chat",
output_type: "chat"
};

const options = {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'LANGFLOW_API_KEY',
'X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY': 'sk-...',
'X-LANGFLOW-GLOBAL-VAR-USER_ID': 'user123',
'X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT': 'production'
},
body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID', options)
.then(response => response.json())
.then(data => console.log(data))
.catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
"$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
-H "Content-Type: application/json" \
-H "x-api-key: $LANGFLOW_API_KEY" \
-H "X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \
-H "X-LANGFLOW-GLOBAL-VAR-USER_ID: user123" \
-H "X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT: production" \
-d '{
"input_value": "Tell me about something interesting!",
"input_type": "chat",
"output_type": "chat"
}'
```

</TabItem>
</Tabs>

If your flow components reference variables that aren't provided in headers or your Langflow database, the flow fails by default. To avoid this, you can set `LANGFLOW_FALLBACK_TO_ENV_VAR=True` in your `.env` file, which allows the flow to use values from OS environment variables if they aren't otherwise specified.


## Webhook run flow

Use the `/webhook` endpoint to start a flow by sending an HTTP `POST` request.
Expand Down
Loading
Loading