Get started with the DataStax Langflow API

This release contains access to DataStax Langflow as a Tech Preview. The Tech Preview is intended for you to view the capabilities of DataStax Langflow, and to provide your feedback to the product team. You are permitted to use the information only for evaluation purposes and not for use in a production environment. IBM provides the information without obligation of support and "as is" without warranty of any kind.

The DataStax Langflow API provides programmatic access to run flows and receive webhook notifications. This API enables you to integrate Langflow workflows into your applications and automate flow execution.

Prerequisites

Sign in or create an Astra account
Create a flow
Create an application token with the Langflow Administrator or Organization Administrator role. The API uses application tokens for authentication. These are the same tokens used for other DataStax services like Astra DB. The token is passed in the Authorization: Bearer APPLICATION_TOKEN header.

Use the Langflow API to run flows

The Langflow API is the primary way to access your flows and Langflow servers programmatically. To help you embed Langflow API requests in your scripts, Langflow automatically generates Python, JavaScript, and curl code snippets for your flows. To get these code snippets, do the following:

In Langflow, open the flow that you want to embed in your application.
Click Share, and then select API access.

These code snippets call the /v1/run/$FLOW_ID endpoint, and they automatically populate minimum values, like the Langflow server URL, flow ID, headers, and request parameters.

Windows paths

The paths generated by the API access pane assume a *nix environment. If you use Microsoft Windows or WSL, you might need to adjust the filepaths given in the code snippets.
Optional: Click Input Schema to modify component parameters in the code snippets without changing the flow itself.
Click Generate Token to create a token with the Langflow Administrator role.
In the snippet, replace APPLICATION_TOKEN with your application token.

Copy the snippet for the language that you want to use.

The default code in the API access pane constructs a request with the Langflow server url, headers, and a payload of request data. The code snippets automatically include the DATASTAX_LANGFLOW_URL, DATASTAX_ORG_ID, and FLOW_ID values for the flow.

Python
JavaScript
curl

import requests
import os
import uuid

url = "https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/run/FLOW_ID"  # The complete API endpoint URL for this flow

# Request payload configuration
payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!"
}
payload["session_id"] = str(uuid.uuid4())

# Request headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer APPLICATION_TOKEN",
    "X-DataStax-Current-Org": "DATASTAX_ORG_ID"
}

try:
    # Send API request
    response = requests.request("POST", url, json=payload, headers=headers)
    response.raise_for_status()  # Raise exception for bad status codes

    # Print response
    print(response.text)

except requests.exceptions.RequestException as e:
    print(f"Error making API request: {e}")
except ValueError as e:
    print(f"Error parsing response: {e}")

const payload = {
    "output_type": "chat",
    "input_type": "chat",
    "input_value": "hello world!"
};
payload.session_id = crypto.randomUUID();

const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer APPLICATION_TOKEN',
        'X-DataStax-Current-Org': 'DATASTAX_ORG_ID'
    },
    body: JSON.stringify(payload)
};

fetch('https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/run/FLOW_ID', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

curl --request POST \
     --url 'https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/run/FLOW_ID?stream=false' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer APPLICATION_TOKEN' \
     --header 'X-DataStax-Current-Org: DATASTAX_ORG_ID' \
     --data '{
		           "output_type": "chat",
		           "input_type": "chat",
		           "input_value": "hello world!",
		           "session_id": "YOUR_SESSION_ID_HERE" # optional custom session ID
		         }'

# A 200 response confirms the call succeeded.

Run the snippet as is, or use the snippet in the context of a larger script.

Organization IDs in the Langflow API

The API uses two different organization IDs:

LANGFLOW_TENANT_ID: Appears in the URL path, and it identifies the Langflow tenant to connect to.
DATASTAX_ORG_ID: Appears in the request header as x-datastax-current-org, and it identifies your Astra organization.

If you have multiple Langflow tenants or Astra organizations, it’s important to use the correct tenant and organization IDs in your requests.

Run flow endpoint

Endpoint

POST /api/v1/run/FLOW_ID

Description

Execute a flow with the provided input data and return the execution results.

Headers

Content-Type: application/json (required)
Authorization: Bearer APPLICATION_TOKEN (required)
X-DataStax-Current-Org: DATASTAX_ORG_ID (required)

Path and query parameters

flow_id (required): A path parameter identifying the flow to run by it’s flow ID.
stream (optional): A query parameter that enables streaming responses. The default is false (disabled).

Request body parameters

output_type (optional): Output format type. The default is "chat".
input_type (optional): Input format type, either "chat" (default) or "text".
input_value (optional): The literal input content, such as a chat prompt or text string.
session_id (optional): A conversation context ID for maintaining chat history.

Request example

curl --request POST \
     --url 'https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/run/FLOW_ID?stream=false' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer APPLICATION_TOKEN' \
     --header 'X-DataStax-Current-Org: DATASTAX_ORG_ID' \
     --data '{
               "output_type": "chat",
               "input_type": "chat",
               "input_value": "hello world!",
               "session_id": "YOUR_SESSION_ID_HERE"
             }'

Response

{
  "session_id": "a24abcc0-0d1a-4467-aff3-fd80637310fa",
  "outputs": [
    {
      "inputs": {
        "input_value": "hello world!"
      },
      "outputs": []
    }
  ]
}

Trigger flows with webhooks

You can use the Webhook component to start a flow run in response to an external event. The webhook endpoint allows external applications to trigger flows by sending data directly to your flow.

To receive requests at the /webhook endpoint, your flow must contain a webhook component. To get your webhook endpoint with values for DATASTAX_LANGFLOW_URL, LANGFLOW_TENANT_ID, and FLOW_ID already completed, add a webhook component to your flow, and then copy the value from the Endpoint field. The DataStax org ID must be in the header as x-datastax-current-org. The webhook endpoint follows the pattern https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/webhook/FLOW_ID.

For more information, see Trigger flows with webhooks.

Python
JavaScript
curl

import requests
import json

url = "https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/webhook/FLOW_ID"

# Webhook payload data
payload = {
    "id": "12345",
    "name": "alex",
    "email": "alex@email.com"
}

# Request headers
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer APPLICATION_TOKEN",
    "X-DataStax-Current-Org": "DATASTAX_ORG_ID"
}

try:
    # Send webhook request
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()

    # Print response
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"Error sending webhook: {e}")

const url = 'https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/webhook/FLOW_ID';

// Webhook payload data
const payload = {
    "id": "12345",
    "name": "alex",
    "email": "alex@email.com"
};

const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer APPLICATION_TOKEN',
        'X-DataStax-Current-Org': 'DATASTAX_ORG_ID'
    },
    body: JSON.stringify(payload)
};

fetch(url, options)
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(err => console.error(err));

curl -X POST "https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/webhook/FLOW_ID" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer APPLICATION_TOKEN" \
     -H "X-DataStax-Current-Org: DATASTAX_ORG_ID" \
     -d '{
       "id": "12345",
       "name": "alex",
       "email": "alex@email.com"
      }'

A successful webhook request returns a confirmation that the flow has started.

{
  "message": "Task started in the background",
  "status": "in progress"
}

Webhook endpoint

Endpoint

POST /api/v1/webhook/FLOW_ID

Description

Trigger a flow execution by sending data directly to the webhook endpoint.

Headers

Content-Type: application/json (required)
Authorization: Bearer APPLICATION_TOKEN (required)
X-DataStax-Current-Org: DATASTAX_ORG_ID (required)

Path parameters

flow_id (required): The unique identifier of the flow to execute.

Request body

Any JSON data structure that your flow expects. The webhook will pass this data directly to your flow as input.

Request example

curl -X POST "https://DATASTAX_LANGFLOW_URL/lf/LANGFLOW_TENANT_ID/api/v1/webhook/FLOW_ID" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer APPLICATION_TOKEN" \
     -H "X-DataStax-Current-Org: DATASTAX_ORG_ID" \
     -d '{
       "id": "12345",
       "name": "alex",
       "email": "alex@email.com"
     }'

Response

{
  "message": "Task started in the background",
  "status": "in progress"
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK: Request successful (run endpoint)
202 Accepted: Request accepted (webhook endpoint)
401 Unauthorized: Authentication required (invalid token, missing headers, wrong organization)
404 Not Found: Flow not found (invalid flow ID, invalid endpoint)

Limits

Any HTTP API call, such as flow execution, has a 10 minute completion limit. After 10 minutes, the backend will time out the request.

File uploads are limited to 200 MB. For more information, see Manage files.