---
title: "Create a listing"
method: POST
path: "/api/items"
tags: ["Listings"]
---

# Create a listing

`POST /api/items`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/items`
- 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`)

Upload photos and create an AI-generated listing. Supports Idempotency-Key for safe retries.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `photos` string[], required

## Response `200`

Listing created — but check `data.inactive`. An over-the-active-limit item is NOT refused: it is saved with `status: 'inactive'` and the response carries `inactive: true`. An inactive item is not on the sale page, so reporting it as a live listing is wrong; tell the seller it is saved but needs an upgrade (or a freed slot) to go live.

- object
  - `success` boolean
  - `data` object
    - `inactive` boolean: Present and true only when the item was saved as status 'inactive' because the active-item limit is reached.

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `403`: Creation ceiling reached for the current tier (active-item limit or lifetime cap). The error message names the limit; the fix is an upgrade via POST /api/payments/checkout-link. Also `code: ADDRESS_IN_PUBLIC_LISTING` when an API key or OAuth token writes the seller's stored street address into public listing text (title, description, transport_notes, condition, category, or specifications). Nothing is saved. Remove the address; to give it to a buyer, use the address share flow. A signed-in seller's own session is not checked.
- `409`: This account has no email on file, so an assistant cannot publish a listing (agent credentials only). Nothing was saved. Not retryable until the account has an email. 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.
- `500`: Unexpected server error.

---

[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)