> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload, list, download, and delete files via the API

## What is the Files API?

The **Files** API is your project’s file storage: you upload images or documents (PDFs, text, etc.), and each file gets a unique **file ID**. You can then use that ID in other parts of Flowra — for example in [knowledge](/guides/knowledge) collections (RAG), as attachments in [workflows](/guides/workflows), or in your own app logic (e.g. “show the user’s uploaded contract”). Files are scoped to your project and secured with your API key; you list, download, or delete them via the API.

So: upload once, get an ID; use the ID wherever you need to refer to that file (knowledge, workflow input, your backend).

### Example use cases

* **Knowledge base** — Users upload PDFs or docs; you upload them via the Files API and add them to a [knowledge](/guides/knowledge) collection so the agent can answer from that content.
* **Workflow attachments** — A workflow “summarize this document” receives a file ID in the input; your app uploaded the file earlier and passes the ID when running the workflow.
* **Image in chat** — User sends an image in your UI; you upload it with the Files API, then send the file ID to the agent or workflow so it can “see” the image.

### How it works

1. **Upload** — `POST /file/upload/single/{fileType}` with the file (e.g. `image`, `document`). Response includes the file ID.
2. **List** — Paginated list of files in the project (optional filters). Use to build a file picker or library.
3. **Download / delete** — Get the file by ID (or by filename) for download; delete when no longer needed.

Supported file types and extensions are available via the file-types endpoints so you can validate before upload.

***

## API endpoints

### List supported file types

**GET** `/api/v1/file/fileTypes` returns all supported file types and their allowed extensions. Use this to build upload forms or validate file types before uploading.

**GET** `/api/v1/file/fileType/{fileType}` returns allowed extensions and metadata for one type (e.g. `image`, `document`).

### List files

**GET** `/api/v1/file` returns a paginated list of files in your project. Use query parameters for pagination and filters (see [API reference](/api-reference)).

<CodeGroup>
  ```bash theme={null}
  curl -X GET "https://flowra.dev/api/v1/file?limit=20" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

### Upload a file

**POST** `/api/v1/file/upload/single/{fileType}` uploads one file via **multipart/form-data**. Put the file type in the path (e.g. `image`, `document`). The request body must include a `file` field (binary). The response returns the **file ID** to use in other APIs (e.g. knowledge, workflows).

<CodeGroup>
  ```bash theme={null}
  curl -X POST "https://flowra.dev/api/v1/file/upload/single/image" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "file=@/path/to/your/image.png"
  ```
</CodeGroup>

### Download and delete

* **GET** `/api/v1/file/download/{id}` — Download a file by ID. Returns the file content with the appropriate content-type.
* **GET** `/api/v1/file/{filename}` — Serve a file by its stored filename (e.g. for public or signed URLs).
* **DELETE** `/api/v1/file/{id}` — Permanently delete a file. It will no longer be available for download or use in workflows.

## Related

* [API reference: file](/api-reference) — Full request/response schemas and query parameters.