langflow/docs/versioned_docs/version-1.8.0/API-Reference/api-files.mdx

---
title: Files endpoints
slug: /api-files
---

Use the `/files` endpoints to move files between your local machine and Langflow.

All `/files` endpoints (both `/v1/files` and `/v2/files`) require authentication with a Langflow API key.
You can only access files that belong to your own user account, even as a superuser.

## Differences between `/v1/files` and `/v2/files`

There are two versions of the `/files` endpoints.

`/v2/files` offers the following improvements over `/v1/files`:

- `/v2` files are organized by `user_id` instead of `flow_id`.
  This means files are owned by users, and they aren't attached to specific flows.
  You can upload a file to Langflow one time, and use it with multiple flows.
- `/v2` files are tracked in the Langflow database.
- `/v2` supports bulk upload and delete.
- `/v2` responses contain more descriptive metadata.

However, `/v2/files` doesn't support image files.
To send image files to your flows through the API, use [Upload image files (v1)](#upload-image-files-v1).

## Files/V1 endpoints

Use the `/files` endpoints to move files between your local machine and Langflow.

### Upload file (v1)

Upload a file to the `v1/files/upload/$FLOW_ID` endpoint:
Replace **FILE_NAME** with the uploaded file name.

```bash
curl -X POST \
  "$LANGFLOW_URL/api/v1/files/upload/$FLOW_ID" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -F "file=@FILE_NAME.txt"
```

Replace `FILE_NAME.txt` with the name and extension of the file you want to upload.
Not all file types are supported.

<details>
<summary>Result</summary>

```json
{
  "flowId": "92f9a4c5-cfc8-4656-ae63-1f0881163c28",
  "file_path": "92f9a4c5-cfc8-4656-ae63-1f0881163c28/2024-12-30_15-19-43_your_file.txt"
}
```

</details>

### Upload image files (v1)

Send image files to Langflow to use them in flows.

The default file limit is 1024 MB.
To change this limit, set the `LANGFLOW_MAX_FILE_SIZE_UPLOAD` [environment variable](/environment-variables).

1. Attach the image to a `POST /v1/files/upload/$FLOW_ID` request with `--form` (`-F`) and the file path:

    ```bash
    curl -X POST "$LANGFLOW_URL/api/v1/files/upload/$FLOW_ID" \
      -H "Content-Type: multipart/form-data" \
      -H "x-api-key: $LANGFLOW_API_KEY" \
      -F "file=@PATH/TO/FILE.png"
    ```

    A successful request returns the `file_path` for the image in the Langflow file management system in the format `FLOW_ID/TIMESTAMP_FILENAME.TYPE`.
    For example:

    ```json
    {
      "flowId": "a430cc57-06bb-4c11-be39-d3d4de68d2c4",
      "file_path": "a430cc57-06bb-4c11-be39-d3d4de68d2c4/2024-11-27_14-47-50_image-file.png"
    }
    ```

2. Use the returned `file_path` to send the image file to other components that can accept file input. Where you specify the file path depends on the component type.

    The following example runs the **Basic Prompting** template flow, passing the image file and the query `describe this image` as input for the **Chat Input** component.
    In this case, the file path is specified in `tweaks`.

    ```bash
    curl -X POST \
        "$LANGFLOW_URL/api/v1/run/a430cc57-06bb-4c11-be39-d3d4de68d2c4?stream=false" \
        -H "Content-Type: application/json" \
        -H "x-api-key: $LANGFLOW_API_KEY" \
        -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": "describe this image"
          }
        }
      }'
    ```

    :::tip
    For help with tweaks, use the **Input Schema** in a flow's [**API access** pane](/concepts-publish#api-access).
    Setting tweaks with **Input Schema** also automatically populates the required component IDs.
    :::

### List files (v1)

List all files associated with a specific flow.

```bash
curl -X GET \
  "$LANGFLOW_URL/api/v1/files/list/$FLOW_ID" \
  -H "accept: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY"
```

<details>
<summary>Result</summary>

```json
{
  "files": ["2024-12-30_15-19-43_your_file.txt"]
}
```

</details>

### Download file (v1)

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_your_file.txt" \
  -H "accept: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  --output downloaded_file.txt
```

<details>
<summary>Result</summary>

```text
File contents downloaded to downloaded_file.txt
```

</details>

### Delete file (v1)

Delete a specific file from a flow.

```bash
curl -X DELETE \
  "$LANGFLOW_URL/api/v1/files/delete/$FLOW_ID/2024-12-30_15-19-43_your_file.txt" \
  -H "accept: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY"
```

<details>
<summary>Result</summary>

```json
{
  "message": "File 2024-12-30_15-19-43_your_file.txt deleted successfully"
}
```

</details>

## Files/V2 endpoints

Use the `/files` endpoints to move files between your local machine and Langflow.

The `/v2/files` endpoints can be authenticated by an API key or JWT.
To create a Langflow API key and export it as an environment variable, see [Get started with the Langflow API](/api-reference-api-examples).

### 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 `07e5b864-e367-4f52-b647-a48035ae7e5e/d44dc2e1-9ae9-4cf6-9114-8d34a6126c94.pdf`.

1. To retrieve your current `user_id`, call the `/whoami` endpoint:

    ```bash
    curl -X GET \
      "$LANGFLOW_URL/api/v1/users/whoami" \
      -H "accept: application/json" \
      -H "x-api-key: $LANGFLOW_API_KEY"
    ```

    <details>
    <summary>Result</summary>

    ```
    {"id":"07e5b864-e367-4f52-b647-a48035ae7e5e","username":"langflow","profile_image":null,"store_api_key":null,"is_active":true,"is_superuser":true,"create_at":"2025-05-08T17:59:07.855965","updated_at":"2025-05-28T19:00:42.556460","last_login_at":"2025-05-28T19:00:42.554338","optins":{"github_starred":false,"dialog_dismissed":true,"discord_clicked":false,"mcp_dialog_dismissed":true}}
    ```

    </details>

2. In the POST request to `v2/files`, replace **@FILE_NAME.EXTENSION** with the uploaded file name and its extension.
You must include the ampersand (`@`) in the request to instruct curl to upload the contents of the file, not the string `FILE_NAME.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"
    ```

    The file is uploaded in the format `USER_ID/FILE_ID.FILE_EXTENSION`, and the API returns metadata about the uploaded file:

    ```json
    {
      "id":"d44dc2e1-9ae9-4cf6-9114-8d34a6126c94",
      "name":"engine_manual",
      "path":"07e5b864-e367-4f52-b647-a48035ae7e5e/d44dc2e1-9ae9-4cf6-9114-8d34a6126c94.pdf",
      "size":851160,
      "provider":null
    }
    ```

### Send files to your flows (v2)

:::info
The `/v2/files` endpoint can't send image files to flows.
To send image files to your flows through the API, see [Upload image files (v1)](#upload-image-files-v1).
:::

This endpoint uploads files to your Langflow server's file management system.
To use an uploaded file in a flow, send the file path to a flow with a [**Read File** component](/read-file).

The default file limit is 1024 MB. To configure this value, change the `LANGFLOW_MAX_FILE_SIZE_UPLOAD` [environment variable](/environment-variables).

1. To send a file to your flow with the API, POST the file to the `/api/v2/files` endpoint.

    Replace **FILE_NAME.EXTENSION** with the name and extension of the file you want to upload.
    This is the same step described in [Upload file (v2)](#upload-file-v2), but since you need the filename to upload to your flow, it is included here.

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

    The file is uploaded in the format `USER_ID/FILE_ID.FILE_EXTENSION`, and the API returns metadata about the uploaded file:

    ```json
    {
      "id":"d44dc2e1-9ae9-4cf6-9114-8d34a6126c94",
      "name":"engine_manual",
      "path":"07e5b864-e367-4f52-b647-a48035ae7e5e/d44dc2e1-9ae9-4cf6-9114-8d34a6126c94.pdf",
      "size":851160,
      "provider": null
    }
    ```

2. To use this file in your flow, add a **Read File** component to your flow.
This component loads files into flows from your local machine or Langflow file management.

3. Run the flow, passing the `path` to the `Read-File` component in the `tweaks` object:

    ```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": {
        "Read-File-1olS3": {
          "path": [
            "07e5b864-e367-4f52-b647-a48035ae7e5e/3a290013-fe1e-4d3d-a454-cacae81288f3.pdf"
          ]
        }
      }
    }'
    ```

    To get the `Read-File` component's ID, call the [Read flow](/api-flows#read-flow) endpoint or inspect the component in the visual editor.

    If the file path is valid, the flow runs successfully.

### 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"
```

<details>
<summary>Result</summary>

```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
  }
]
```

</details>

### Download file (v2)

Download a specific file by its ID and file extension.

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
```

<details>
<summary>Result</summary>

```text
File contents downloaded to downloaded_file.txt
```

</details>

### 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"
```

<details>
<summary>Result</summary>

```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
}
```

</details>

### 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"
```

<details>
<summary>Result</summary>

```json
{
  "message": "File deleted successfully"
}
```

</details>

### 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"
```

<details>
<summary>Result</summary>

```json
{
  "message": "All files deleted successfully"
}
```

</details>

## Create upload file (Deprecated)

This endpoint is deprecated. Use the `/files` endpoints instead.

## See also

* [Manage files](/concepts-file-management)