---
title: "Upload a photo batch (step 1 of bulk creation)"
method: POST
path: "/api/items/bulk-upload"
tags: ["Listings"]
---

# Upload a photo batch (step 1 of bulk creation)

`POST /api/items/bulk-upload`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/items/bulk-upload`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

Uploads up to 50 base64 photos to Storage and returns their URLs plus a batchId — synchronously, HTTP 200, no AI. This is step 1 of the bulk chain: bulk-upload (photos → URLs) → POST /api/items/bulk-generate (URLs → AI listings via job polling) → POST /api/items (save). It does NOT group photos or generate listings itself. Supports Idempotency-Key for safe retries.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `photos` string[], required

## Response `200`

Photos stored.

- object
  - `success` boolean
  - `data` object
    - `fullUrls` string[]
    - `thumbnailUrls` string[]
    - `batchId` string
    - `count` number

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `409`: A photo is still uploading (sent with Retry-After: 5). Retry after the delay. Also returned with `code: idempotency_conflict` while a request with the same Idempotency-Key is still being processed; that one is worth retrying with the same key after a few seconds. A 409 without that code is the operation's own refusal: read `error`.
- `422`: `code: idempotency_key_reuse`. While an earlier request with this Idempotency-Key is still running or succeeded within the last 24h, the key was sent to the same operation with a different body (compared byte for byte) or from a different kind of credential (signed-in session, API key, or OAuth token). Nothing was executed and the original record is untouched, so retrying with this key repeats the 422. Send the request with a new key.
- `429`: Too many requests.

---

[API](https://skmtc.dev/clearlist/apis/clearlist-api.md) · [All operations](https://skmtc.dev/clearlist/apis/clearlist-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clearlist/apis/clearlist-api/revisions/b1c1c4221cb8?raw)