> For the complete documentation index, see [llms.txt](https://docs.lingoql.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lingoql.com/sub0/apis-abi/file-uploads.md).

# File Uploads

File uploads use the `UPLOAD` action mode.

They work with auth, chaining, database writes, and background execution.

### Basic upload

```json
{
  "id": 1,
  "mode": "UPLOAD",
  "uploads": {
    "max_file_uploads": 1,
    "max_upload_file_size": 20971520,
    "allowed_mimetypes": ["image/png", "image/jpeg"],
    "upload_folder": "/gallery"
  },
  "returnables": ["url", "file_size"]
}
```

Use `multipart/form-data` when calling upload endpoints.

### Upload options

| Property               | Purpose                      |
| ---------------------- | ---------------------------- |
| `max_file_uploads`     | Max files per request        |
| `max_upload_file_size` | Max file size in bytes       |
| `allowed_mimetypes`    | Whitelisted file types       |
| `upload_folder`        | Storage path                 |
| `expiration`           | File expiration              |
| `delete_files`         | Deletes files by storage key |

### Dynamic upload paths

Use accessors in the path:

```json
"upload_folder": "/users/$PROTECTED.id/avatar"
```

Or generate a folder name:

```json
"upload_folder": "/uploads/$GENERATOR.NANOID"
```

### Upload response

Uploads return structured metadata.

```json
[
  {
    "storage_key": "gallery/123/avatar.png",
    "original_file_name": "avatar.png",
    "new_file_name": "a92k3d.png",
    "url": "https://cdn.lingoql.com/...",
    "file_type": "image/png",
    "extension": "png",
    "file_size": 204800,
    "dominant_color": "#e8a32f"
  }
]
```

Use `returnables` to reduce the response shape.

### Store upload results in the database

The next actionable receives the upload result automatically.

```json
{
  "id": 2,
  "mode": "QUERY",
  "sql_query": {
    "query": "INSERT INTO gallery (url, size) VALUES ($1, $2)",
    "parameters": ["url", "file_size"]
  }
}
```

### Delete files

Use an upload action with `delete_files: true` and send an array of storage keys.

```json
"uploads": {
  "delete_files": true
}
```

```json
["gallery/123/avatar.png"]
```

### Protect uploads

Protect upload endpoints the same way you protect any other endpoint.

```json
"protected": {
  "provide_as": "x-access-token",
  "extract_claims": ["id"]
}
```

This makes user-scoped folders easy:

```json
"upload_folder": "/gallery/$PROTECTED.id"
```

### Why this matters

Uploads are usually where backend complexity starts.

In Sub0, they stay inside the same ABI model as everything else.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lingoql.com/sub0/apis-abi/file-uploads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.