Pixeloa

Who am I, what plan am I on, and what credits do I have. Requires scope: read_usage.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

List the account's items (newest first, cursor-paginated). Query: limit (1–100, default 25), cursor (created_at ISO string from next_cursor), status. Requires scope: read_catalog.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 25
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from a previous page (created_at ISO string)"
    },
    "status": {
      "type": "string",
      "description": "Filter by item status"
    }
  },
  "additionalProperties": false
}

Create an item from 1–4 image URLs and start analysis. 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. Requires scope: upload_images.

{
  "type": "object",
  "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"
        }
      }
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "title",
    "image_urls"
  ],
  "additionalProperties": false
}

Get one item, including status and next_allowed_actions. Requires scope: read_catalog.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Update the item's public-page settings (product CTA link). 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. Requires scope: publish_items.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "product_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "maxLength": 2048
    },
    "product_cta_label": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 60
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Delete an item (unpublishes first; removes images and models). 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. CHANGES PUBLIC STATE. Requires scope: upload_images.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Confirm the item's real-world dimensions (cm). Allowed once analysis has finished (status 'awaiting_confirmation', or 'failed' with a completed analysis) and before generation. Moves the item to 'confirmed'. Requires scope: confirm_scale.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "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
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id",
    "dimensions_cm"
  ],
  "additionalProperties": false
}

Start 3D generation (spends the account's credits). 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. SPENDS CREDITS: confirm with the account owner unless they delegated this. Requires scope: start_generation.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Publish the item's public AR page. 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. CHANGES PUBLIC STATE. Requires scope: publish_items.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Unpublish the item's public AR page (all embeds go quiet). CHANGES PUBLIC STATE. Requires scope: publish_items.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Public AR URL, embed URL, embed snippets and QR (if generated). Requires scope: read_catalog.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Generate (or regenerate) the item's QR code SVG. Requires scope: create_qr.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

List the account's catalogs. Requires scope: read_catalog.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Delete a catalog (unpublishes its public page first). 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). CHANGES PUBLIC STATE. Requires scope: write_catalog.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Add an item to a catalog (appends unless position is given). Both the catalog and the item must belong to the key's account (404 otherwise). 409 conflict when the item is not ready (details.status says where it is), is not eligible for catalogs, is unlisted (link only), or is already in the catalog. Requires scope: write_catalog.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    },
    "position": {
      "type": "integer",
      "minimum": 0
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id",
    "item_id"
  ],
  "additionalProperties": false
}

Remove an item from a catalog. Requires scope: write_catalog.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "itemId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID"
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional Idempotency-Key: repeat-safe retries return the original result."
    }
  },
  "required": [
    "id",
    "itemId"
  ],
  "additionalProperties": false
}

Generation options available to this account and their current credit cost. 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. Requires scope: read_usage.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

The account's credit ledger (newest first, cursor-paginated). Every debit and credit: generation charges, refunds, plan allocations, top-ups. Query: limit (1–100), cursor (created_at from next_cursor). Requires scope: read_usage.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 50
    },
    "cursor": {
      "type": "string",
      "description": "next_cursor from a previous page"
    }
  },
  "additionalProperties": false
}

List the account's agent identities. 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. Requires scope: read_usage.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

List the account's webhook endpoints and the event types. 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. Requires scope: read_usage.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}