From 6b8d622c5a2ed7f62a1cede3b9afe311cfb50549 Mon Sep 17 00:00:00 2001 From: Mendon Kissling <59585235+mendonk@users.noreply.github.com> Date: Thu, 17 Apr 2025 15:02:45 -0400 Subject: [PATCH] docs: v2 files api examples (#7369) * initial * more * v1-and-v2-upload * local-storage-note * tested-delete-download-delete-all-and-list * add-put-command-and-test * test-upload * file-name-and-extension * docs: update API reference for file uploads * add-api-var * Apply suggestions from code review Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com> * capitalization * v1-v2-clarification * last-clarification * file-name-and-extension --------- Co-authored-by: KimberlyFields <46325568+KimberlyFields@users.noreply.github.com> --- .../api-reference-api-examples.md | 326 ++++++++++++++---- 1 file changed, 267 insertions(+), 59 deletions(-) diff --git a/docs/docs/API-Reference/api-reference-api-examples.md b/docs/docs/API-Reference/api-reference-api-examples.md index b1a077f1c..bd56f2ec5 100644 --- a/docs/docs/API-Reference/api-reference-api-examples.md +++ b/docs/docs/API-Reference/api-reference-api-examples.md @@ -497,7 +497,7 @@ The `/build/{flow_id}/flow` endpoint accepts the following parameters in its req ### Configure the build endpoint -The `/build` endpoint accepts optional values for `start_component_id` and `stop_component_id` to control where the flow run will start and stop. +The `/build` endpoint accepts optional values for `start_component_id` and `stop_component_id` to control where the flow run starts and stops. Setting `stop_component_id` for a component triggers the same behavior as clicking the **Play** button on that component, where all dependent components leading up to that component are also run. For example, to stop flow execution at the Open AI model component, run the following command: @@ -547,12 +547,27 @@ curl -X POST \ Use the `/files` endpoint to add or delete files between your local machine and Langflow. -### Upload file +There are `/v1` and `/v2` versions of the `/files` endpoints. +The `v2/files` version offers several improvements over `/v1`: -Upload a file to an existing flow. +* In `v1`, files are organized by `flow_id`. In `v2`, files are organized by `user_id`. +This means files are accessed based on user ownership, and not tied to specific flows. +You can upload a file to Langflow one time, and use it with multiple flows. +* In `v2`, files are tracked in the Langflow database, and can be added or deleted in bulk, instead of one by one. +* Responses from the `/v2` endpoint contain more descriptive metadata. +* The `v2` endpoints require authentication by an API key or JWT. -This example uploads `the_oscar_award.csv`. +## Files/V1 endpoints +Use the `/files` endpoint to add or delete files between your local machine and Langflow. + +* In `v1`, files are organized by `flow_id`. +* In `v2`, files are organized by `user_id` and tracked in the Langflow database, and can be added or deleted in bulk, instead of one by one. + +### Upload file (v1) + +Upload a file to the `v1/files/upload/` endpoint of your flow. +Replace **FILE_NAME** with the uploaded file name. @@ -561,7 +576,7 @@ curl -X POST \ "$LANGFLOW_URL/api/v1/files/upload/$FLOW_ID" \ -H "accept: application/json" \ -H "Content-Type: multipart/form-data" \ - -F "file=@the_oscar_award.csv" + -F "file=@FILE_NAME.txt" ``` @@ -570,14 +585,14 @@ curl -X POST \ ```json { "flowId": "92f9a4c5-cfc8-4656-ae63-1f0881163c28", - "file_path": "92f9a4c5-cfc8-4656-ae63-1f0881163c28/2024-12-30_15-19-43_the_oscar_award.csv" + "file_path": "92f9a4c5-cfc8-4656-ae63-1f0881163c28/2024-12-30_15-19-43_your_file.txt" } ``` -#### Upload image files +### Upload image files (v1) Send image files to the Langflow API for AI analysis. @@ -585,11 +600,11 @@ The default file limit is 100 MB. To configure this value, change the `LANGFLOW_ 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/` endpoint of your flow. - +Replace **FILE_NAME** with the uploaded file name. ```bash curl -X POST "$LANGFLOW_URL/api/v1/files/upload/a430cc57-06bb-4c11-be39-d3d4de68d2c4" \ -H "Content-Type: multipart/form-data" \ - -F "file=@image-file.png" + -F "file=@FILE_NAME.png" ``` The API returns the image file path in the format `"file_path":"/_"}`. @@ -600,6 +615,7 @@ The API returns the image file path in the format `"file_path":"/< 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. +To find your Chat input component's ID, use the [](#) ```bash curl -X POST \ @@ -622,8 +638,7 @@ Your chatbot describes the image file you sent. "text": "This flowchart appears to represent a complex system for processing financial inquiries using various AI agents and tools. Here's a breakdown of its components and how they might work together..." ``` - -### List files +### List files (v1) List all files associated with a specific flow. @@ -642,7 +657,7 @@ curl -X GET \ ```json { "files": [ - "2024-12-30_15-19-43_the_oscar_award.csv" + "2024-12-30_15-19-43_your_file.txt" ] } ``` @@ -650,79 +665,40 @@ curl -X GET \ -### Download file +### Download file (v1) -Download a specific file for a given flow. - -To look up the file name in Langflow, use the `/list` endpoint. - -This example downloads the `2024-12-30_15-19-43_the_oscar_award.csv` file from Langflow to a file named `output-file.csv`. - -The `--output` flag is optional. +Download a specific file from a flow. ```bash curl -X GET \ - "$LANGFLOW_URL/api/v1/files/download/$FLOW_ID/2024-12-30_15-19-43_the_oscar_award.csv" \ + "$LANGFLOW_URL/api/v1/files/download/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \ -H "accept: application/json" \ - --output output-file.csv + --output downloaded_file.txt ``` ```text -The file contents. +File contents downloaded to downloaded_file.txt ``` -### Download image - -Download an image file for a given flow. - -To look up the file name in Langflow, use the `/list` endpoint. - -This example downloads the `2024-12-30_15-42-44_image-file.png` file from Langflow to a file named `output-image.png`. - -The `--output` flag is optional. - - - - -```bash -curl -X GET \ - "$LANGFLOW_URL/api/v1/files/images/$FLOW_ID/2024-12-30_15-42-44_image-file.png" \ - -H "accept: application/json" \ - --output output-image.png -``` - - - - -```text -Image file content. -``` - - - - - -### Delete file +### Delete file (v1) Delete a specific file from a flow. -This example deletes the `2024-12-30_15-42-44_image-file.png` file from Langflow. - ```bash curl -X DELETE \ - "$LANGFLOW_URL/api/v1/files/delete/$FLOW_ID/2024-12-30_15-42-44_image-file.png" \ + "$LANGFLOW_URL/api/v1/files/delete/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \ -H "accept: application/json" ``` @@ -731,7 +707,239 @@ curl -X DELETE \ ```json { - "message": "File 2024-12-30_15-42-44_image-file.png deleted successfully" + "message": "File 2024-12-30_15-19-43_your_file.txt deleted successfully" +} +``` + + + + +## Files/V2 endpoints + +In `v2`, files are organized by `user_id` and tracked in the Langflow database, and can be added or deleted in bulk, instead of one by one. +The `v2` endpoints require authentication by an API key or JWT. +To create a Langflow API key and export it as an environment variable, see [Export values](#export-values). + +### Upload file (v2) + +Upload a file to your user account. The file can be used across multiple flows. + +The file is uploaded in the format `USER_ID/FILE_ID.FILE_EXTENSION`, such as `6f17a73e-97d7-4519-a8d9-8e4c0be411bb/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34.txt`. +Replace **FILE_NAME.EXTENSION** with the uploaded file name and its extension. + + + +```bash +curl -X POST \ + "$LANGFLOW_URL/api/v2/files" \ + -H "accept: application/json" \ + -H "Content-Type: multipart/form-data" \ + -H "x-api-key: $LANGFLOW_API_KEY" \ + -F "file=@FILE_NAME.EXTENSION" +``` + + + + +```json +{ + "id": "c7b22c4c-d5e0-4ec9-af97-5d85b7657a34", + "name": "FILE_NAME.EXTENSION", + "path": "6f17a73e-97d7-4519-a8d9-8e4c0be411bb/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34.txt", + "size": 1234, + "provider": null +} +``` + + + + +### Send files to your flows (v2) + +Send a file to your flow for analysis using the [File](/components-data#file) component. + +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 `/api/v2/files` endpoint. +Replace **FILE_NAME** with the uploaded file name. +```bash +curl -X POST "$LANGFLOW_URL/api/v2/files" \ + -H "Content-Type: multipart/form-data" \ + -H "x-api-key: $LANGFLOW_API_KEY" \ + -F "file=@FILE_NAME.png" +``` + +The file is uploaded in the format `USER_ID/FILE_ID.FILE_EXTENSION`, and the API returns metadata about the uploaded file: + +```json +{ + "id": "5f829bc4-ac1e-4a80-b1d1-fedc03cd5b6e", + "name": "FILE_NAME", + "path": "232f54ba-dd54-4760-977e-ed637f83e785/5f829bc4-ac1e-4a80-b1d1-fedc03cd5b6e.png", + "size": 84408, + "provider": null +} +``` + +2. To use this file in your flow, add a [File](/components-data#file) component to load a file into the flow. +3. To load the file into your flow, send it to the **File** component. + +```text +curl --request POST \ + --url '$LANGFLOW_URL/api/v1/run/$FLOW_ID' \ + --header 'Content-Type: application/json' \ + --header 'x-api-key: $LANGFLOW_API_KEY' \ + --data '{ + "input_value": "what do you see?", + "output_type": "chat", + "input_type": "text", + "tweaks": { + "File-t2Ngc": { + "path": [ + "232f54ba-dd54-4760-977e-ed637f83e785/5f829bc4-ac1e-4a80-b1d1-fedc03cd5b6e.png" + ] + } + } +}' +``` + +### List files (v2) + +List all files associated with your user account. + + + + +```bash +curl -X GET \ + "$LANGFLOW_URL/api/v2/files" \ + -H "accept: application/json" \ + -H "x-api-key: $LANGFLOW_API_KEY" +``` + + + + +```json +[ + { + "id": "c7b22c4c-d5e0-4ec9-af97-5d85b7657a34", + "name": "your_file", + "path": "6f17a73e-97d7-4519-a8d9-8e4c0be411bb/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34.txt", + "size": 1234, + "provider": null + } +] +``` + + + + +### Download file (v2) + +Download a specific file by its ID and file extension. + +:::tip +You must specify the file type you expect in the `--output` value. +::: + + + + +```bash +curl -X GET \ + "$LANGFLOW_URL/api/v2/files/c7b22c4c-d5e0-4ec9-af97-5d85b7657a34" \ + -H "accept: application/json" \ + -H "x-api-key: $LANGFLOW_API_KEY" \ + --output downloaded_file.txt +``` + + + + +```text +File contents downloaded to downloaded_file.txt +``` + + + + +### Edit file name (v2) + +Change a file name. + + + + +```bash +curl -X PUT \ + "$LANGFLOW_URL/api/v2/files/$FILE_ID?name=new_file_name" \ + -H "accept: application/json" \ + -H "x-api-key: $LANGFLOW_API_KEY" +``` + + + + +```json +{ + "id":"76543e40-f388-4cb3-b0ee-a1e870aca3d3", + "name":"new_file_name", + "path":"6f17a73e-97d7-4519-a8d9-8e4c0be411bb/76543e40-f388-4cb3-b0ee-a1e870aca3d3.png", + "size":2728251, + "provider":null + } +``` + + + +### Delete file (v2) + +Delete a specific file by its ID. + + + + +```bash +curl -X DELETE \ + "$LANGFLOW_URL/api/v2/files/$FILE_ID" \ + -H "accept: application/json" \ + -H "x-api-key: $LANGFLOW_API_KEY" +``` + + + + +```json +{ + "message": "File deleted successfully" +} +``` + + + + +### Delete all files (v2) + +Delete all files associated with your user account. + + + + +```bash +curl -X DELETE \ + "$LANGFLOW_URL/api/v2/files" \ + -H "accept: application/json" \ + -H "x-api-key: $LANGFLOW_API_KEY" +``` + + + + +```json +{ + "message": "All files deleted successfully" } ```