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

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",