jyapayne/langflow
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

docs: v2 files api examples (#7369)

Browse source 
* 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>
This commit is contained in:
Mendon Kissling 2025-04-17 15:02:45 -04:00 • committed by GitHub
commit 6b8d622c5a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 267 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

326
docs/docs/API-Reference/api-reference-api-examples.md
View file

@ -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/<YOUR-FLOW-ID>` endpoint of your flow.
Replace **FILE_NAME** with the uploaded file name.
<Tabs>
<TabItem value="curl" label="curl" default>
@ -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"
```
</TabItem>
@ -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"
}
```
</TabItem>
</Tabs>
#### 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/<YOUR-FLOW-ID>` 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":"<YOUR-FLOW-ID>/<TIMESTAMP>_<FILE-NAME>"}`.
@ -600,6 +615,7 @@ The API returns the image file path in the format `"file_path":"<YOUR-FLOW-ID>/<
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 \
</TabItem>
</Tabs>
### 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.
<Tabs>
<TabItem value="curl" label="curl" default>
```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
```
</TabItem>
<TabItem value="result" label="Result">
```text
The file contents.
File contents downloaded to downloaded_file.txt
```
</TabItem>
</Tabs>
### 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.
<Tabs>
<TabItem value="curl" label="curl" default>
```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
```
</TabItem>
<TabItem value="result" label="Result">
```text
Image file content.
```
</TabItem>
</Tabs>
### 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.
<Tabs>
<TabItem value="curl" label="curl" default>
```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"
}
```
</TabItem>
</Tabs>
## 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.
<Tabs>
<TabItem value="curl" label="curl" default>
```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"
```
</TabItem>
<TabItem value="result" label="Result">
```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
}
```
</TabItem>
</Tabs>
### 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.
<Tabs>
<TabItem value="curl" label="curl" default>
```bash
curl -X GET \
"$LANGFLOW_URL/api/v2/files" \
-H "accept: application/json" \
-H "x-api-key: $LANGFLOW_API_KEY"
```
</TabItem>
<TabItem value="result" label="Result">
```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
}
]
```
</TabItem>
</Tabs>
### 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.
:::
<Tabs>
<TabItem value="curl" label="curl" default>
```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
```
</TabItem>
<TabItem value="result" label="Result">
```text
File contents downloaded to downloaded_file.txt
```
</TabItem>
</Tabs>
### Edit file name (v2)
Change a file name.
<Tabs>
<TabItem value="curl" label="curl" default>
```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"
```
</TabItem>
<TabItem value="result" label="Result">
```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
}
```
</TabItem>
</Tabs>
### Delete file (v2)
Delete a specific file by its ID.
<Tabs>
<TabItem value="curl" label="curl" default>
```bash
curl -X DELETE \
"$LANGFLOW_URL/api/v2/files/$FILE_ID" \
-H "accept: application/json" \
-H "x-api-key: $LANGFLOW_API_KEY"
```
</TabItem>
<TabItem value="result" label="Result">
```json
{
"message": "File deleted successfully"
}
```
</TabItem>
</Tabs>
### Delete all files (v2)
Delete all files associated with your user account.
<Tabs>
<TabItem value="curl" label="curl" default>
```bash
curl -X DELETE \
"$LANGFLOW_URL/api/v2/files" \
-H "accept: application/json" \
-H "x-api-key: $LANGFLOW_API_KEY"
```
</TabItem>
<TabItem value="result" label="Result">
```json
{
"message": "All files deleted successfully"
}
```