{"openapi":"3.1.0","info":{"title":"Pixeloa API","version":"2026-08-16","description":"Turn product photos into true-scale 3D models and AR pages, then publish, embed and catalog them. Every call acts on behalf of the account that owns the API key, within that key's scopes. Generation spends the account's credits; billing itself always requires a human in the dashboard.","x-status":"beta","x-upload-limits":{"source":"GET /v1/generation/options → images{min,max,accepted_mime_types,max_file_size_bytes} (registry-driven; the active provider's limits apply)","url_rules":"public https; not pixeloa.ai itself; no private networks; redirects re-validated; streamed size cap"},"x-actor-model":{"actor_types":["human","agent","service"],"rule":"Every principal acts on behalf of a human account. GET /v1/me returns actor.type and actor.agent. Keys attached to an agent report that agent; keys with no agent, and session tokens, act as the human. Suspending an agent kills all its keys instantly.","spend_caps":"Optional per-key and per-agent daily credit caps (UTC day). A generate call that would exceed one fails with 403 spend_cap_exceeded before anything is spent; GET /v1/me shows spend_today."},"x-rate-limits":{"per_key_per_minute":120,"per_account_per_minute":600,"credit_spending_per_account_per_minute":30,"headers":["RateLimit-Limit","RateLimit-Remaining","RateLimit-Reset","RateLimit-Policy"],"on_limit":"429 rate_limited + Retry-After"},"x-idempotency":{"header":"Idempotency-Key","applies_to":"every non-GET request","replay_header":"Idempotent-Replayed: true","ttl_hours":24,"reuse_with_different_body":"422 validation_error (details.code=idempotency_key_reused)","concurrent":"409 conflict (details.code=idempotency_in_progress)"},"x-webhooks":{"events":["item.analysis_completed","item.analysis_failed","item.generation_completed","item.generation_failed","item.published","item.unpublished","account.credits_low"],"signature_header":"Pixeloa-Signature","scheme":"t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>"}},"servers":[{"url":"https://pixeloa.ai"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"pxk_live_…","description":"Create keys in the dashboard under Account → API keys. Send as `Authorization: Bearer pxk_live_…`. Scopes: read_catalog (Read items, catalogs and their public links); write_catalog (Create catalogs; add, remove and reorder catalog items); upload_images (Create items and upload their photos); start_generation (Start 3D generation (spends the account's credits)); confirm_scale (Confirm or correct real-world dimensions); publish_items (Publish / unpublish item AR pages); publish_catalog (Reserved: catalog publish endpoints are not yet exposed on /v1); manage_billing (Reserved: billing reads are covered by read_usage today; checkout always requires a human); read_usage (Read credit balance and usage); create_qr (Generate QR codes and embed snippets)"}},"responses":{"Error":{"description":"Error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden_scope","not_found","validation_error","conflict","insufficient_credits","rate_limited","spend_cap_exceeded","plan_limit_reached","provider_unavailable","internal_error"]},"message":{"type":"string"},"details":{},"request_id":{"type":"string"}}}}},"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","analyzing","awaiting_confirmation","confirmed","generating","ready","failed"]},"visibility":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"dimensions_cm":{"type":"object","properties":{"confirmed":{"type":["object","null"]},"estimated":{"type":["object","null"]}}},"model":{"type":"object","properties":{"available":{"type":"boolean"},"sha256":{"type":["string","null"]}}},"public":{"type":"object","properties":{"published":{"type":"boolean"},"slug":{"type":["string","null"]},"ar_url":{"type":["string","null"],"format":"uri"},"embed_url":{"type":["string","null"],"format":"uri"}}},"publishable":{"type":"object","description":"Row-level pre-check for POST /publish; POST /publish reports the exact resolver state on 409.","properties":{"ok":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"string","enum":["generation_not_finished","no_model","archived","restricted_category"]}}}},"next_allowed_actions":{"type":"array","items":{"type":"string","enum":["upload_images","wait_for_analysis","confirm_scale","start_generation","wait_for_generation","publish","unpublish","add_to_catalog"]}}}}}},"paths":{"/v1/me":{"get":{"operationId":"getMe","summary":"Who am I, what plan am I on, and what credits do I have","tags":["me"],"security":[{"apiKey":["read_usage"]}],"x-required-scope":"read_usage","responses":{"200":{"description":"Account, business, plan (slug, monthly_credits, published_item_limit), credit balance (total / included / bonus / purchased), principal, actor and spend_today.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items":{"get":{"operationId":"listItems","summary":"List the account's items (newest first, cursor-paginated)","description":"Query: limit (1–100, default 25), cursor (created_at ISO string from next_cursor), status.","tags":["items"],"security":[{"apiKey":["read_catalog"]}],"x-required-scope":"read_catalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createItem","summary":"Create an item from 1–4 image URLs and start analysis","description":"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.","tags":["items"],"security":[{"apiKey":["upload_images"]}],"x-required-scope":"upload_images","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","image_urls"],"properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000},"image_urls":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"string","format":"uri"}},"owner_dims_cm":{"type":"object","properties":{"width_cm":{"type":"number"},"height_cm":{"type":"number"},"depth_cm":{"type":"number"}}}}}}}},"responses":{"201":{"description":"The created item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}":{"get":{"operationId":"getItem","summary":"Get one item, including status and next_allowed_actions","tags":["items"],"security":[{"apiKey":["read_catalog"]}],"x-required-scope":"read_catalog","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"updateItem","summary":"Update the item's public-page settings (product CTA link)","description":"Sets the 'view product' button shown on the public AR page and embeds. product_url must be a public https URL on your own site, and it may not point at pixeloa.ai itself or a private network (422 validation_error otherwise). Pass null to clear it (the label clears with it). product_cta_label (max 60 chars) overrides the default button text. Clicks are counted in the owner's analytics.","tags":["items"],"security":[{"apiKey":["publish_items"]}],"x-required-scope":"publish_items","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_url":{"type":["string","null"],"format":"uri","maxLength":2048},"product_cta_label":{"type":["string","null"],"maxLength":60}}}}}},"responses":{"200":{"description":"The updated item (see product_cta).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteItem","summary":"Delete an item (unpublishes first; removes images and models)","description":"Permanent. A published item is unpublished first so its AR page and embeds go quiet, then its images, models and QR are removed. Requires the same scope as creating items.","tags":["items"],"security":[{"apiKey":["upload_images"]}],"x-required-scope":"upload_images","x-confirmation":"changes_public_state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/confirm":{"post":{"operationId":"confirmScale","summary":"Confirm the item's real-world dimensions (cm)","description":"Allowed once analysis has finished (status 'awaiting_confirmation', or 'failed' with a completed analysis) and before generation. Moves the item to 'confirmed'.","tags":["items"],"security":[{"apiKey":["confirm_scale"]}],"x-required-scope":"confirm_scale","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dimensions_cm"],"properties":{"dimensions_cm":{"type":"object","required":["width_cm","height_cm","depth_cm"],"properties":{"width_cm":{"type":"number"},"height_cm":{"type":"number"},"depth_cm":{"type":"number"}}},"notes":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/generate":{"post":{"operationId":"startGeneration","summary":"Start 3D generation (spends the account's credits)","description":"Requires status 'confirmed' with confirmed dimensions (a 'failed' generation may be attempted again on the same item; it was refunded and has no result). A 'ready' item is never regenerated in place; for another result create a new item from the images. Asynchronous: poll GET /v1/items/{id} until model.available is true. Fails with 402 insufficient_credits when the balance is too low, 409 conflict when the state does not allow it.","tags":["items"],"security":[{"apiKey":["start_generation"]}],"x-required-scope":"start_generation","x-confirmation":"spends_credits","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/publish":{"post":{"operationId":"publishItem","summary":"Publish the item's public AR page","description":"Makes the item public (this is the owner's publish decision; items created via the API start private) subject to the plan's published-item limit (403 plan_limit_reached), verifies eligibility (409 conflict with details.state / details.blockers when the model, scale or category policy blocks it), mints the public slug on first publish and returns the item with public.ar_url and public.embed_url set. Check item.publishable before calling.","tags":["items"],"security":[{"apiKey":["publish_items"]}],"x-required-scope":"publish_items","x-confirmation":"changes_public_state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/unpublish":{"post":{"operationId":"unpublishItem","summary":"Unpublish the item's public AR page (all embeds go quiet)","tags":["items"],"security":[{"apiKey":["publish_items"]}],"x-required-scope":"publish_items","x-confirmation":"changes_public_state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/links":{"get":{"operationId":"getItemLinks","summary":"Public AR URL, embed URL, embed snippets and QR (if generated)","tags":["items"],"security":[{"apiKey":["read_catalog"]}],"x-required-scope":"read_catalog","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/items/{id}/qr":{"post":{"operationId":"generateItemQr","summary":"Generate (or regenerate) the item's QR code SVG","tags":["items"],"security":[{"apiKey":["create_qr"]}],"x-required-scope":"create_qr","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/catalogs":{"get":{"operationId":"listCatalogs","summary":"List the account's catalogs","tags":["catalogs"],"security":[{"apiKey":["read_catalog"]}],"x-required-scope":"read_catalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/catalogs/{id}":{"delete":{"operationId":"deleteCatalog","summary":"Delete a catalog (unpublishes its public page first)","description":"Permanent. A published catalog is unpublished first so its public page, QR and embeds go quiet; item memberships are removed (the items themselves are untouched); if it was the primary catalog that pointer clears. The platform demo catalog cannot be deleted (409 conflict).","tags":["catalogs"],"security":[{"apiKey":["write_catalog"]}],"x-required-scope":"write_catalog","x-confirmation":"changes_public_state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/catalogs/{id}/items":{"post":{"operationId":"addCatalogItem","summary":"Add an item to a catalog (appends unless position is given)","tags":["catalogs"],"security":[{"apiKey":["write_catalog"]}],"x-required-scope":"write_catalog","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["item_id"],"properties":{"item_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/catalogs/{id}/items/{itemId}":{"delete":{"operationId":"removeCatalogItem","summary":"Remove an item from a catalog","tags":["catalogs"],"security":[{"apiKey":["write_catalog"]}],"x-required-scope":"write_catalog","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/generation/options":{"get":{"operationId":"listGenerationOptions","summary":"Generation options available to this account and their current credit cost","description":"Read before spending. Each option lists credit_cost (what POST /v1/items/{id}/generate will debit for that provider), release_stage, image limits and output formats; is_default marks the provider used when the item has none pinned. GET /v1/items/{id} additionally returns generation.estimated_credit_cost for that item.","tags":["generation"],"security":[{"apiKey":["read_usage"]}],"x-required-scope":"read_usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/credits/ledger":{"get":{"operationId":"listCreditLedger","summary":"The account's credit ledger (newest first, cursor-paginated)","description":"Every debit and credit: generation charges, refunds, plan allocations, top-ups. Query: limit (1–100), cursor (created_at from next_cursor).","tags":["credits"],"security":[{"apiKey":["read_usage"]}],"x-required-scope":"read_usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/agents":{"get":{"operationId":"listAgents","summary":"List the account's agent identities","description":"An agent is an identity OWNED by the account (kind agent or service). Keys attach to an agent; the agent gets actor identity, an optional daily credit cap and its own audit trail, but every call still runs as the owner. Agents are created and suspended by a human in the dashboard.","tags":["agents"],"security":[{"apiKey":["read_usage"]}],"x-required-scope":"read_usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/webhooks":{"get":{"operationId":"listWebhookEndpoints","summary":"List the account's webhook endpoints and the event types","description":"Endpoints are created by a human in the dashboard (Account → API keys → Webhooks); a key can list them but never add or redirect one. Deliveries are signed with Pixeloa-Signature (t=<unix>,v1=<hex HMAC-SHA256(secret, t + \".\" + body)>), retried with backoff for up to 12h, and auto-disabled after 20 consecutive failures.","tags":["webhooks"],"security":[{"apiKey":["read_usage"]}],"x-required-scope":"read_usage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}}}