docs: API examples (#5499)

* bump-api-to-1.1.1

* docs: api reference content

* more-endpoints

* cleanup

* all-endpoints-accounted-for

* docs: update API reference with user response examples and authorization header

* all-200s-complete

* fix-spacing-for-gh-preview

* sidebars

* monitor-endpoints

* fix-build-error

* fix-sidebar-error

* create-flows

* flows-endpoint-finished

* move

* files-endpoint

* run-flow

* folder-endpoint

* docs: update API reference with new endpoints and examples for flows, folders, and files

* value

* docs: update openapi.json

* docs: enhance API reference with folder-id export instructions and examples

* docs: update API reference with new flow structure and log retrieval instructions

* docs: clarify ZIP file download endpoint description in API examples

* docs: refine API examples for clarity and consistency

* docs: refine API examples for clarity and consistency

* webhook

* docs: format curl example for improved readability

* docs: update curl examples to use double quotes for variable interpolation

* docs: Update API example descriptions for improved clarity

* docs: Update API example descriptions for improved clarity

* docs: Enhance API reference with Langflow API key setup and build flow examples

* docs: update API reference examples with new event data and structure

* docs: add clarification on LLM chat response streaming in API examples

* error-and-build-vertex

* docs: remove wrong information from API examples

* Apply suggestions from code review

Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com>

* docs: Update API reference examples for environment variable exports

* docs: Fix JSON structure in API reference examples

* docs: Update API reference examples for file download and log retrieval

---------

Co-authored-by: anovazzi1 <otavio2204@gmail.com>
Co-authored-by: Gabriel Luiz Freitas Almeida <gabriel@langflow.org>
Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com>
This commit is contained in:
Mendon Kissling 2025-01-15 12:10:05 -05:00 committed by GitHub
commit 26ed6dc2f7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 1888 additions and 95 deletions

File diff suppressed because one or more lines are too long

View file

@ -37,58 +37,12 @@ The **Tweaks** tab displays the available parameters for your flow. Modifying
## Send image files to your flow with the API
Send image files to the Langflow API for AI analysis.
The default file limit is 100 MB. To configure this value, change the `LANGFLOW_MAX_FILE_SIZE_UPLOAD` environment variable.
For more information, see [Supported environment variables](/environment-variables#supported-variables).
1. To send an image to your flow with the API, POST the image file to the `v1/files/upload/<YOUR-FLOW-ID>` endpoint of your flow.
```curl
curl -X POST "http://127.0.0.1:7860/api/v1/files/upload/a430cc57-06bb-4c11-be39-d3d4de68d2c4" \
-H "Content-Type: multipart/form-data" \
-F "file=@image-file.png"
```
The API returns the image file path in the format `"file_path":"<YOUR-FLOW-ID>/<TIMESTAMP>_<FILE-NAME>"}`.
```json
{"flowId":"a430cc57-06bb-4c11-be39-d3d4de68d2c4","file_path":"a430cc57-06bb-4c11-be39-d3d4de68d2c4/2024-11-27_14-47-50_image-file.png"}
```
2. Post the image file to the **Chat Input** component of a **Basic prompting** flow.
Pass the file path value as an input in the **Tweaks** section of the curl call to Langflow.
```curl
curl -X POST \
"http://127.0.0.1:7860/api/v1/run/a430cc57-06bb-4c11-be39-d3d4de68d2c4?stream=false" \
-H 'Content-Type: application/json'\
-d '{
"output_type": "chat",
"input_type": "chat",
"tweaks": {
"ChatInput-b67sL": {
"files": "a430cc57-06bb-4c11-be39-d3d4de68d2c4/2024-11-27_14-47-50_image-file.png",
"input_value": "what do you see?"
}
}}'
```
Your chatbot describes the image file you sent.
```plain
"text": "This flowchart appears to represent a complex system for processing financial inquiries using various AI agents and tools. Heres a breakdown of its components and how they might work together..."
```
## Chat Widget {#48f121a6cb3243979a341753da0c2700}
---
For information on sending files to the Langflow API, see [API examples](/api-reference-api-examples#upload-image-files).
## Chat Widget
The **Chat Widget HTML** tab displays code that can be inserted in the `<body>` of your HTML to interact with your flow.
The **Langflow Chat Widget** is a powerful web component that enables communication with a Langflow project. This widget allows for a chat interface embedding, allowing the integration of Langflow into web applications effortlessly.

View file

@ -2,7 +2,7 @@
"openapi": "3.1.0",
"info": {
"title": "Langflow",
"version": "1.1.0"
"version": "1.1.1"
},
"paths": {
"/api/v1/build/{flow_id}/vertices": {
@ -361,8 +361,8 @@
"tags": [
"Base"
],
"summary": "Simplified Run Flow",
"description": "Executes a specified flow by ID.\n\nExecutes a specified flow by ID with input customization, performance enhancements through caching,\nand optional data streaming.\n\n### Parameters:\n- `db` (Session): Database session for executing queries.\n- `flow_id_or_name` (str): ID or endpoint name of the flow to run.\n- `input_request` (SimplifiedAPIRequest): Request object containing input values, types, output selection, tweaks,\n and session ID.\n- `api_key_user` (User): User object derived from the provided API key, used for authentication.\n- `session_service` (SessionService): Service for managing flow sessions, essential for session reuse and caching.\n\n### SimplifiedAPIRequest:\n- `input_value` (Optional[str], default=\"\"): Input value to pass to the flow.\n- `input_type` (Optional[Literal[\"chat\", \"text\", \"any\"]], default=\"chat\"): Type of the input value,\n determining how the input is interpreted.\n- `output_type` (Optional[Literal[\"chat\", \"text\", \"any\", \"debug\"]], default=\"chat\"): Desired type of output,\n affecting which components' outputs are included in the response. If set to \"debug\", all outputs are returned.\n- `output_component` (Optional[str], default=None): Specific component output to retrieve. If provided,\n only the output of the specified component is returned. This overrides the `output_type` parameter.\n- `tweaks` (Optional[Tweaks], default=None): Adjustments to the flow's behavior, allowing for custom execution\n parameters.\n- `session_id` (Optional[str], default=None): An identifier for reusing session data, aiding in performance for\n subsequent requests.\n\n\n### Tweaks\nA dictionary of tweaks to customize the flow execution.\nThe tweaks can be used to modify the flow's parameters and components.\nTweaks can be overridden by the input values.\nYou can use Component's `id` or Display Name as key to tweak a specific component\n(e.g., `{\"Component Name\": {\"parameter_name\": \"value\"}}`).\nYou can also use the parameter name as key to tweak all components with that parameter\n(e.g., `{\"parameter_name\": \"value\"}`).\n\n### Returns:\n- A `RunResponse` object containing the execution results, including selected (or all, based on `output_type`)\n outputs of the flow and the session ID, facilitating result retrieval and further interactions in a session\n context.\n\n### Raises:\n- HTTPException: 404 if the specified flow ID curl -X 'POST' \n### Example:\n```bash\ncurl -X 'POST' 'http://<your_server>/run/{flow_id}' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: YOU_API_KEY' -H '\n -d '{\n \"input_value\": \"Sample input\",\n \"input_type\": \"chat\",\n \"output_type\": \"chat\",\n \"tweaks\": {},\n }'\n```\n\nThis endpoint provides a powerful interface for executing flows with enhanced flexibility and efficiency,\nsupporting a wide range of applications by allowing for dynamic input and output configuration along with\nperformance optimizations through session management and caching.",
"summary": "Run Flow",
"description": "Executes a specified flow by ID with support for streaming and telemetry.\n\nThis endpoint executes a flow identified by ID or name, with options for streaming the response\nand tracking execution metrics. It handles both streaming and non-streaming execution modes.\n\nArgs:\n background_tasks (BackgroundTasks): FastAPI background task manager\n flow (FlowRead | None): The flow to execute, loaded via dependency\n input_request (SimplifiedAPIRequest | None): Input parameters for the flow\n stream (bool): Whether to stream the response\n api_key_user (UserRead): Authenticated user from API key\n request (Request): The incoming HTTP request\n\nReturns:\n Union[StreamingResponse, RunResponse]: Either a streaming response for real-time results\n or a RunResponse with the complete execution results\n\nRaises:\n HTTPException: For flow not found (404) or invalid input (400)\n APIException: For internal execution errors (500)\n\nNotes:\n - Supports both streaming and non-streaming execution modes\n - Tracks execution time and success/failure via telemetry\n - Handles graceful client disconnection in streaming mode\n - Provides detailed error handling with appropriate HTTP status codes\n - In streaming mode, uses EventManager to handle events:\n - \"add_message\": New messages during execution\n - \"token\": Individual tokens during streaming\n - \"end\": Final execution result",
"operationId": "simplified_run_flow_api_v1_run__flow_id_or_name__post",
"security": [
{
@ -398,6 +398,9 @@
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"format": "uuid"
@ -432,9 +435,7 @@
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunResponse"
}
"schema": {}
}
}
},
@ -475,6 +476,9 @@
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"format": "uuid"
@ -809,7 +813,7 @@
"Base"
],
"summary": "Custom Component Update",
"description": "Update a custom component with the provided code request.\n\nThis endpoint generates the CustomComponentFrontendNode normally but then runs the `update_build_config` method\non the latest version of the template.\nThis ensures that every time it runs, it has the latest version of the template.\n\nArgs:\n code_request (CustomComponentRequest): The code request containing the updated code for the custom component.\n user (User, optional): The user making the request. Defaults to the current active user.\n\nReturns:\n dict: The updated custom component node.",
"description": "Update a custom component with the provided code request.\n\nThis endpoint generates the CustomComponentFrontendNode normally but then runs the `update_build_config` method\non the latest version of the template.\nThis ensures that every time it runs, it has the latest version of the template.\n\nArgs:\n code_request (CustomComponentRequest): The code request containing the updated code for the custom component.\n user (User, optional): The user making the request. Defaults to the current active user.\n\nReturns:\n dict: The updated custom component node.\n\nRaises:\n HTTPException: If there's an error building or updating the component\n SerializationError: If there's an error serializing the component to JSON",
"operationId": "custom_component_update_api_v1_custom_component_update_post",
"requestBody": {
"content": {
@ -3362,7 +3366,8 @@
"schema": {
"anyOf": [
{
"type": "string"
"type": "string",
"format": "uuid"
},
{
"type": "null"
@ -3697,6 +3702,33 @@
"format": "uuid",
"title": "Flow Id"
}
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
@ -3705,11 +3737,7 @@
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TransactionReadResponse"
},
"title": "Response Get Transactions Api V1 Monitor Transactions Get"
"$ref": "#/components/schemas/Page_TransactionTable_"
}
}
}
@ -3838,6 +3866,7 @@
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Folder Id"
}
},
@ -3959,6 +3988,7 @@
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Folder Id"
}
}
@ -4020,6 +4050,7 @@
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Folder Id"
}
}
@ -4067,6 +4098,7 @@
"required": true,
"schema": {
"type": "string",
"format": "uuid",
"title": "Folder Id"
}
}
@ -4187,6 +4219,50 @@
]
}
},
"/api/v1/mcp/sse": {
"get": {
"tags": [
"mcp"
],
"summary": "Handle Sse",
"operationId": "handle_sse_api_v1_mcp_sse_get",
"responses": {
"200": {
"description": "Successful Response"
}
},
"security": [
{
"OAuth2PasswordBearer": []
},
{
"API key query": []
},
{
"API key header": []
}
]
}
},
"/api/v1/mcp/": {
"post": {
"tags": [
"mcp"
],
"summary": "Handle Messages",
"operationId": "handle_messages_api_v1_mcp__post",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/health": {
"get": {
"tags": [
@ -4858,9 +4934,7 @@
"title": "Code"
},
"CodeContent": {
"type": "object",
"title": "CodeContent",
"description": "Content type for code snippets."
"type": "object"
},
"CodeValidationResponse": {
"properties": {
@ -5122,9 +5196,7 @@
"title": "EdgeDataDetails"
},
"ErrorContent": {
"type": "object",
"title": "ErrorContent",
"description": "Content type for error messages."
"type": "object"
},
"ErrorLog": {
"properties": {
@ -5304,6 +5376,18 @@
"title": "Tags",
"default": []
},
"locked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Locked",
"default": false
},
"id": {
"type": "string",
"format": "uuid",
@ -5464,6 +5548,18 @@
],
"title": "Tags"
},
"locked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Locked",
"default": false
},
"user_id": {
"anyOf": [
{
@ -5535,11 +5631,13 @@
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
"title": "Id",
"description": "Unique identifier for the flow"
},
"name": {
"type": "string",
"title": "Name"
"title": "Name",
"description": "The name of the flow"
},
"folder_id": {
"anyOf": [
@ -5551,7 +5649,8 @@
"type": "null"
}
],
"title": "Folder Id"
"title": "Folder Id",
"description": "The ID of the folder containing the flow. None if not associated with a folder"
},
"is_component": {
"anyOf": [
@ -5562,7 +5661,8 @@
"type": "null"
}
],
"title": "Is Component"
"title": "Is Component",
"description": "Flag indicating whether the flow is a component"
},
"endpoint_name": {
"anyOf": [
@ -5573,7 +5673,8 @@
"type": "null"
}
],
"title": "Endpoint Name"
"title": "Endpoint Name",
"description": "The name of the endpoint associated with this flow"
},
"description": {
"anyOf": [
@ -5584,7 +5685,20 @@
"type": "null"
}
],
"title": "Description"
"title": "Description",
"description": "A description of the flow"
},
"data": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"title": "Data",
"description": "The data of the component, if is_component is True"
}
},
"type": "object",
@ -5593,7 +5707,7 @@
"name"
],
"title": "FlowHeader",
"description": "Model representing a header for a flow - Without the data.\n\nAttributes:\n-----------\nid : UUID\n Unique identifier for the flow.\nname : str\n The name of the flow.\nfolder_id : UUID | None, optional\n The ID of the folder containing the flow. None if not associated with a folder.\nis_component : bool | None, optional\n Flag indicating whether the flow is a component.\nendpoint_name : str | None, optional\n The name of the endpoint associated with this flow.\ndescription : str | None, optional\n A description of the flow."
"description": "Model representing a header for a flow - Without the data."
},
"FlowListCreate": {
"properties": {
@ -5734,6 +5848,18 @@
],
"title": "Tags"
},
"locked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Locked",
"default": false
},
"id": {
"type": "string",
"format": "uuid",
@ -5830,6 +5956,17 @@
}
],
"title": "Endpoint Name"
},
"locked": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Locked"
}
},
"type": "object",
@ -6145,6 +6282,11 @@
"title": "Documentation",
"default": ""
},
"minimized": {
"type": "boolean",
"title": "Minimized",
"default": false
},
"custom_fields": {
"anyOf": [
{
@ -6335,6 +6477,11 @@
"title": "Documentation",
"default": ""
},
"minimized": {
"type": "boolean",
"title": "Minimized",
"default": false
},
"custom_fields": {
"anyOf": [
{
@ -6658,9 +6805,7 @@
]
},
"JSONContent": {
"type": "object",
"title": "JSONContent",
"description": "Content type for JSON content."
"type": "object"
},
"ListComponentResponse": {
"properties": {
@ -6899,9 +7044,7 @@
"title": "Log"
},
"MediaContent": {
"type": "object",
"title": "MediaContent",
"description": "Content type for media content."
"type": "object"
},
"MessageRead": {
"properties": {
@ -7176,6 +7319,16 @@
}
],
"title": "Error"
},
"properties": {
"anyOf": [
{
"$ref": "#/components/schemas/Properties"
},
{
"type": "null"
}
]
}
},
"type": "object",
@ -7500,6 +7653,73 @@
],
"title": "Page[Flow]"
},
"Page_TransactionTable_": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/TransactionTable"
},
"type": "array",
"title": "Items"
},
"total": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Total"
},
"page": {
"anyOf": [
{
"type": "integer",
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Page"
},
"size": {
"anyOf": [
{
"type": "integer",
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Size"
},
"pages": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size"
],
"title": "Page[TransactionTable]"
},
"PlaygroundEvent": {
"properties": {
"properties": {
@ -7687,6 +7907,17 @@
"title": "Allow Markdown",
"default": false
},
"positive_feedback": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Positive Feedback"
},
"state": {
"type": "string",
"enum": [
@ -8328,9 +8559,7 @@
"description": "Task status response schema."
},
"TextContent": {
"type": "object",
"title": "TextContent",
"description": "Content type for simple text content."
"type": "object"
},
"Token": {
"properties": {
@ -8356,11 +8585,9 @@
"title": "Token"
},
"ToolContent": {
"type": "object",
"title": "ToolContent",
"description": "Content type for tool start content."
"type": "object"
},
"TransactionReadResponse": {
"TransactionTable": {
"properties": {
"timestamp": {
"type": "string",
@ -8417,20 +8644,26 @@
"format": "uuid",
"title": "Flow Id"
},
"transaction_id": {
"type": "string",
"format": "uuid",
"title": "Transaction Id"
"id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Id"
}
},
"type": "object",
"required": [
"vertex_id",
"status",
"flow_id",
"transaction_id"
"flow_id"
],
"title": "TransactionReadResponse"
"title": "TransactionTable"
},
"Tweaks": {
"additionalProperties": {
@ -8567,6 +8800,11 @@
"template": {
"type": "object",
"title": "Template"
},
"tool_mode": {
"type": "boolean",
"title": "Tool Mode",
"default": false
}
},
"type": "object",

View file

@ -139,9 +139,14 @@ module.exports = {
type: "category",
label: "API Reference",
items: [
{
type: "doc",
id: "API-Reference/api-reference-api-examples",
label: "API examples",
},
{
type: "link",
label: "API Documentation",
label: "API documentation",
href: "/api",
},
],