mirror of
https://github.com/langflow-ai/langflow.git
synced 2026-07-24 02:32:13 +08:00
b36444f5d9
* fix: nightly now properly gets 1.9.0 branch (#12215) before it was attempting to pull release-notes as letters are alphanumerically after numbers when we sort -V then grab tail now we only look at branch names that follow the pattern '^release-[0-9]+\.[0-9]+\.[0-9]+$' * docs: add search icon (#12216) add-back-svg * initial-content * cut-1.8-release-and-include-next-version * stage-1.8.0-and-next --------- Co-authored-by: Adam-Aghili <149833988+Adam-Aghili@users.noreply.github.com>
529 lines
13 KiB
Plaintext
529 lines
13 KiB
Plaintext
---
|
|
title: Workflow API (Beta)
|
|
slug: /workflow-api
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import PartialAPISetup from '@site/docs/_partial-api-setup.mdx';
|
|
|
|
:::warning Beta Feature
|
|
The Workflow API is currently in **Beta**.
|
|
The API endpoints and response formats may change in future releases.
|
|
:::
|
|
|
|
The Workflow API provides programmatic access to execute Langflow workflows synchronously or asynchronously.
|
|
Synchronous requests receive complete results immediately upon completion.
|
|
Asynchronous requests are queued in the background and will run until complete, or a request is issued to the [Stop Workflow endpoint](#stop-workflow-endpoint).
|
|
|
|
The Workflow API is part of the Langflow Developer v2 API and offers enhanced workflow execution capabilities compared to the v1 `/run` endpoint.
|
|
|
|
<PartialAPISetup />
|
|
|
|
## Execute workflows endpoint (synchronous or asynchronous)
|
|
|
|
**Endpoint:**
|
|
|
|
```
|
|
POST /api/v2/workflows
|
|
```
|
|
|
|
**Description:** Execute a workflow synchronously and receive complete results immediately upon completion.
|
|
Set `background=false` to make the request synchronous.
|
|
|
|
### Example synchronous request
|
|
|
|
Execute a workflow synchronously and receive complete results immediately:
|
|
|
|
<Tabs>
|
|
<TabItem value="Python" label="Python" default>
|
|
|
|
```python
|
|
import requests
|
|
|
|
url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
|
|
headers = {
|
|
"Content-Type": "application/json",
|
|
"x-api-key": LANGFLOW_API_KEY
|
|
}
|
|
|
|
payload = {
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"background": False,
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "what is 2+2",
|
|
"ChatInput-abc.session_id": "session-123"
|
|
}
|
|
}
|
|
|
|
response = requests.post(url, json=payload, headers=headers)
|
|
print(response.json())
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="TypeScript" label="TypeScript">
|
|
|
|
```typescript
|
|
import axios from 'axios';
|
|
|
|
const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
|
|
|
|
const payload = {
|
|
flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
background: false,
|
|
inputs: {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "what is 2+2",
|
|
"ChatInput-abc.session_id": "session-123"
|
|
}
|
|
};
|
|
|
|
const runWorkflow = async () => {
|
|
try {
|
|
const response = await axios.post(url, payload, {
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'x-api-key': LANGFLOW_API_KEY
|
|
}
|
|
});
|
|
console.log(response.data);
|
|
} catch (error) {
|
|
console.error('Error triggering workflow:', error);
|
|
}
|
|
};
|
|
|
|
runWorkflow();
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="curl" label="curl">
|
|
|
|
```bash
|
|
curl -X POST \
|
|
"$LANGFLOW_SERVER_URL/api/v2/workflows" \
|
|
-H "Content-Type: application/json" \
|
|
-H "x-api-key: $LANGFLOW_API_KEY" \
|
|
-d '{
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"background": false,
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "what is 2+2",
|
|
"ChatInput-abc.session_id": "session-123"
|
|
}
|
|
}'
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Example asynchronous request
|
|
|
|
For long-running workflows, set `background=true` to get a `job_id` immediately, and then poll the status [using the GET endpoint](#get-workflow-status-endpoint) until the job is complete.
|
|
|
|
To stop a job, send a POST request to the [Stop workflow endpoint](#stop-workflow-endpoint).
|
|
|
|
:::tip
|
|
The asynchronous request contains `stream` parameter, but streaming is not yet supported. The parameter is included for future compatibility.
|
|
:::
|
|
|
|
**Example request:**
|
|
|
|
<Tabs>
|
|
<TabItem value="Python" label="Python" default>
|
|
|
|
```python
|
|
import requests
|
|
|
|
url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
|
|
headers = {
|
|
"Content-Type": "application/json",
|
|
"x-api-key": LANGFLOW_API_KEY
|
|
}
|
|
|
|
payload = {
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"background": True,
|
|
"stream": False,
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "Process this in the background",
|
|
"ChatInput-abc.session_id": "session-456"
|
|
}
|
|
}
|
|
|
|
response = requests.post(url, json=payload, headers=headers)
|
|
print(response.json()) # Returns job_id immediately
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="TypeScript" label="TypeScript">
|
|
|
|
```typescript
|
|
import axios from 'axios';
|
|
|
|
const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
|
|
|
|
const payload = {
|
|
flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
background: true,
|
|
stream: false,
|
|
inputs: {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "Process this in the background",
|
|
"ChatInput-abc.session_id": "session-456"
|
|
}
|
|
};
|
|
|
|
const runWorkflow = async () => {
|
|
try {
|
|
const response = await axios.post(url, payload, {
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'x-api-key': LANGFLOW_API_KEY
|
|
}
|
|
});
|
|
console.log(response.data); // Returns job_id immediately
|
|
} catch (error) {
|
|
console.error('Error triggering workflow:', error);
|
|
}
|
|
};
|
|
|
|
runWorkflow();
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="curl" label="curl">
|
|
|
|
```bash
|
|
curl -X POST \
|
|
"$LANGFLOW_SERVER_URL/api/v2/workflows" \
|
|
-H "Content-Type: application/json" \
|
|
-H "x-api-key: $LANGFLOW_API_KEY" \
|
|
-d '{
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"background": true,
|
|
"stream": false,
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "Process this in the background",
|
|
"ChatInput-abc.session_id": "session-456"
|
|
}
|
|
}'
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"job_id": "job_id_1234567890",
|
|
"created_timestamp": "2025-01-15T10:30:00Z",
|
|
"status": "queued",
|
|
"errors": []
|
|
}
|
|
```
|
|
|
|
### Request body
|
|
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `flow_id` | `string` | Yes | - | The ID or endpoint name of the flow to execute. |
|
|
| `flow_version` | `string` | No | - | Optional version hash to pin to a specific flow version. |
|
|
| `background` | `boolean` | No | `false` | Must be `false` for synchronous execution. |
|
|
| `inputs` | `object` | No | `{}` | Inputs for the workflow execution. Uses component identifiers with dot notation (e.g., `ChatInput-abc.input_value`). See [Component identifiers and input structure](#component-identifiers-and-input-structure) for detailed information. |
|
|
|
|
### Example response
|
|
|
|
```json
|
|
{
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"job_id": "job_id_1234567890",
|
|
"object": "response",
|
|
"created_at": 1741476542,
|
|
"status": "completed",
|
|
"errors": [],
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "what is 2+2",
|
|
"ChatInput-abc.session_id": "session-123"
|
|
},
|
|
"outputs": {
|
|
"ChatOutput-xyz": {
|
|
"type": "message",
|
|
"component_id": "ChatOutput-xyz",
|
|
"status": "completed",
|
|
"content": "2 + 2 equals 4."
|
|
}
|
|
},
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
### Response body
|
|
|
|
The response includes an `outputs` field containing component-level results. Each output has a `type` field indicating the type of content:
|
|
|
|
| Type | Description | Example |
|
|
|------|-------------|---------|
|
|
| `message` | Text message content. | Chat responses, summaries |
|
|
| `image` | Image URL or data. | Generated images, processed images |
|
|
| `sql` | SQL query results. | Database query outputs |
|
|
| `data` | Structured data. | JSON objects, arrays |
|
|
| `file` | File reference. | Generated documents, reports |
|
|
|
|
## Get workflow status endpoint
|
|
|
|
**Endpoint:** `GET /api/v2/workflows`
|
|
|
|
**Description:** Retrieve the status and results of a workflow execution by job ID.
|
|
|
|
### Example request
|
|
|
|
<Tabs>
|
|
<TabItem value="Python" label="Python" default>
|
|
|
|
```python
|
|
import requests
|
|
|
|
url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
|
|
params = {
|
|
"job_id": "job_id_1234567890"
|
|
}
|
|
headers = {
|
|
"accept": "application/json",
|
|
"x-api-key": LANGFLOW_API_KEY
|
|
}
|
|
|
|
response = requests.get(url, params=params, headers=headers)
|
|
print(response.json())
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="TypeScript" label="TypeScript">
|
|
|
|
```typescript
|
|
import axios from 'axios';
|
|
|
|
const jobId = 'job_id_1234567890';
|
|
const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
|
|
|
|
const getWorkflowStatus = async () => {
|
|
try {
|
|
const response = await axios.get(url, {
|
|
params: {
|
|
job_id: jobId
|
|
},
|
|
headers: {
|
|
'accept': 'application/json',
|
|
'x-api-key': LANGFLOW_API_KEY
|
|
}
|
|
});
|
|
console.log(response.data);
|
|
} catch (error) {
|
|
console.error('Error getting workflow status:', error);
|
|
}
|
|
};
|
|
|
|
getWorkflowStatus();
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="curl" label="curl">
|
|
|
|
```bash
|
|
curl -X GET \
|
|
"$LANGFLOW_SERVER_URL/api/v2/workflows?job_id=job_id_1234567890" \
|
|
-H "accept: application/json" \
|
|
-H "x-api-key: $LANGFLOW_API_KEY"
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Query parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `job_id` | `string` | Yes | The job ID returned from a workflow execution. |
|
|
| `stream` | `boolean` | No | If `true`, returns server-sent events stream. Default: `false`. |
|
|
| `sequence_id` | `integer` | No | Optional sequence ID to resume streaming from a specific point. |
|
|
|
|
### Example response
|
|
|
|
```json
|
|
{
|
|
"flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
|
|
"job_id": "job_id_1234567890",
|
|
"object": "response",
|
|
"created_at": 1741476542,
|
|
"status": "completed",
|
|
"errors": [],
|
|
"outputs": {
|
|
"ChatOutput-xyz": {
|
|
"type": "message",
|
|
"component_id": "ChatOutput-xyz",
|
|
"status": "completed",
|
|
"content": "Processing complete..."
|
|
}
|
|
},
|
|
"input": [
|
|
{
|
|
"type": "text",
|
|
"data": "Input text prompt for the workflow execution",
|
|
"role": "User"
|
|
}
|
|
],
|
|
"metadata": {}
|
|
}
|
|
```
|
|
|
|
### Response body
|
|
|
|
The response includes a `status` field that indicates the current state of the workflow execution:
|
|
|
|
| Status | Description |
|
|
|--------|-------------|
|
|
| `queued` | Job is queued and waiting to start. |
|
|
| `in_progress` | Job is currently executing. |
|
|
| `completed` | Job completed successfully. |
|
|
| `failed` | Job failed during execution. |
|
|
| `error` | Job encountered an error. |
|
|
|
|
## Stop workflow endpoint
|
|
|
|
**Endpoint:** `POST /api/v2/workflows/stop`
|
|
|
|
**Description:** Stop a running workflow execution by job ID.
|
|
|
|
### Example request
|
|
|
|
<Tabs>
|
|
<TabItem value="Python" label="Python" default>
|
|
|
|
```python
|
|
import requests
|
|
|
|
url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows/stop"
|
|
headers = {
|
|
"Content-Type": "application/json",
|
|
"x-api-key": LANGFLOW_API_KEY
|
|
}
|
|
payload = {
|
|
"job_id": "job_id_1234567890"
|
|
}
|
|
|
|
response = requests.post(url, json=payload, headers=headers)
|
|
print(response.json())
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="TypeScript" label="TypeScript">
|
|
|
|
```typescript
|
|
import axios from 'axios';
|
|
|
|
const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows/stop`;
|
|
|
|
const payload = {
|
|
job_id: "job_id_1234567890"
|
|
};
|
|
|
|
const stopWorkflow = async () => {
|
|
try {
|
|
const response = await axios.post(url, payload, {
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
'x-api-key': LANGFLOW_API_KEY
|
|
}
|
|
});
|
|
console.log(response.data);
|
|
} catch (error) {
|
|
console.error('Error stopping workflow:', error);
|
|
}
|
|
};
|
|
|
|
stopWorkflow();
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem value="curl" label="curl">
|
|
|
|
```bash
|
|
curl -X POST \
|
|
"$LANGFLOW_SERVER_URL/api/v2/workflows/stop" \
|
|
-H "Content-Type: application/json" \
|
|
-H "x-api-key: $LANGFLOW_API_KEY" \
|
|
-d '{
|
|
"job_id": "job_id_1234567890"
|
|
}'
|
|
```
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
### Request body
|
|
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `job_id` | `string` | Yes | - | The job ID of the workflow to stop. |
|
|
|
|
### Example response
|
|
|
|
```json
|
|
{
|
|
"job_id": "job_id_1234567890",
|
|
"message": "Job job_id_1234567890 cancelled successfully."
|
|
}
|
|
```
|
|
|
|
## Component identifiers and input structure
|
|
|
|
The Workflows API uses component identifiers with dot notation to specify inputs for individual components in your workflow. This allows you to pass values to specific components and override component parameters.
|
|
|
|
Component identifiers use the format `{component_id}.{parameter_name}`.
|
|
When making requests to the Workflows API, include component identifiers in the `inputs` object.
|
|
For example, this demonstrates targeting multiple components and their parameters in a single request.
|
|
|
|
```json
|
|
{
|
|
"flow_id": "your-flow-id",
|
|
"inputs": {
|
|
"ChatInput-abc.input_type": "chat",
|
|
"ChatInput-abc.input_value": "what is 2+2",
|
|
"ChatInput-abc.session_id": "session-123",
|
|
"OpenSearchComponent-xyz.opensearch_url": "https://opensearch:9200",
|
|
"LLMComponent-123.temperature": 0.7,
|
|
"LLMComponent-123.max_tokens": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
To find the component ID in the Langflow UI, open your flow in Langflow, click the component, and then click **Controls**. The component ID is at the top of the **Controls** pane.
|
|
|
|
You can override any component's parameters.
|
|
|
|
## Error handling
|
|
|
|
The API uses standard HTTP status codes to indicate success or failure:
|
|
|
|
| Status Code | Description |
|
|
|-------------|-------------|
|
|
| `200 OK` | Request successful. |
|
|
| `400 Bad Request` | Invalid request parameters. |
|
|
| `401 Unauthorized` | Invalid or missing API key. |
|
|
| `404 Not Found` | Flow not found or developer API disabled. |
|
|
| `500 Internal Server Error` | Server error during execution. |
|
|
| `501 Not Implemented` | Endpoint not yet implemented. |
|
|
|
|
### Error response format
|
|
|
|
```json
|
|
{
|
|
"detail": "Error message describing what went wrong"
|
|
}
|
|
```
|