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

# Folders

> Create and manage folders to organize your uploads

<Info>
  Folders require an API key (`imperial_live_*`) with scopes: - `folders:read` to list folders -
  `folders:write` to create/update/delete folders
</Info>

## List Folders

`GET https://api.imperial.gay/folders`

### Example

```bash theme={null}
curl -X GET "https://api.imperial.gay/folders" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"
```

## Create Folder

`POST https://api.imperial.gay/folders`

Body:

* `name` (string, required)
* `parentId` (string|null, optional)
* `icon` (string, optional)

```bash theme={null}
curl -X POST "https://api.imperial.gay/folders" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Receipts" }'
```

## Update Folder

`PATCH https://api.imperial.gay/folders/:id`

Update any of:

* `name`
* `parentId`
* `icon`

```bash theme={null}
curl -X PATCH "https://api.imperial.gay/folders/6985a036b35713a65e17ccbd" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Receipts 2026" }'
```

## Delete Folder

`DELETE https://api.imperial.gay/folders/:id`

Deletes the folder (and its descendants) and moves contained uploads back to Root.

```bash theme={null}
curl -X DELETE "https://api.imperial.gay/folders/6985a036b35713a65e17ccbd" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"
```