> ## 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.

# Bulk Update Metadata

> Move uploads between folders and/or update tags in bulk

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key in the format: `Bearer imperial_live_xxxxxxxxxxxxx`
</ParamField>

### Body

<ParamField body="ids" type="string[]" required>
  Array of upload IDs to update
</ParamField>

<ParamField body="folderId" type="string|null">
  Destination folder ID. Use `null` to move items to Root.
</ParamField>

<ParamField body="tags" type="string[]">
  Tags to apply (normalized to lowercase)
</ParamField>

<ParamField body="mode" type="string" default="replace">
  Tag mode: `replace`, `add`, or `remove`
</ParamField>

## Response

<ResponseField name="updated" type="number">
  Number of uploads updated
</ResponseField>

## Example

```bash theme={null}
curl -X POST "https://api.imperial.gay/images/bulk-metadata" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["6987cd047baba11ee0f66d98"],
    "folderId": "6985a036b35713a65e17ccbd",
    "tags": ["work", "2026"],
    "mode": "add"
  }'
```