---
title: "Create an item from 1–4 image URLs and start analysis"
method: POST
path: "/v1/items"
tags: ["items"]
---

# Create an item from 1–4 image URLs and start analysis

`POST /v1/items`

## Request

- Base URL: `https://pixeloa.ai`
- URL: `https://pixeloa.ai/v1/items`
- Auth: HTTP bearer

Images are fetched server-side (https only, size- and type-checked against the active provider's limits). The first image is the primary/front view. Image URLs must be publicly reachable and must not point at pixeloa.ai itself (host them on your own site, a CDN, or a public bucket). The item enters 'analyzing'; poll GET /v1/items/{id} until next_allowed_actions contains confirm_scale.

## Request body

- object
  - `title` string, required
  - `description` string
  - `image_urls` string[], required
  - `owner_dims_cm` object
    - `width_cm` number
    - `height_cm` number
    - `depth_cm` number

## Response `201`

The created item.

- Item
  - `id` string, uuid
  - `title` string
  - `description` string, nullable
  - `status` 'draft' | 'analyzing' | 'awaiting_confirmation' | 'confirmed' | 'generating' | 'ready' | 'failed'
  - `visibility` string, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time, nullable
  - `dimensions_cm` object
    - `confirmed` object, nullable
    - `estimated` object, nullable
  - `model` object
    - `available` boolean
    - `sha256` string, nullable
  - `public` object
    - `published` boolean
    - `slug` string, nullable
    - `ar_url` string, uri, nullable
    - `embed_url` string, uri, nullable
  - `publishable` object: Row-level pre-check for POST /publish; POST /publish reports the exact resolver state on 409.
    - `ok` boolean
    - `blockers` string[]
  - `next_allowed_actions` string[]

## Other responses

- `401`: Error envelope
- `403`: Error envelope
- `404`: Error envelope
- `409`: Error envelope
- `422`: Error envelope
- `429`: Error envelope

---

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