Viewrium Docs

API reference

The full /v1 REST surface, request conventions, and how each endpoint maps to the SDKs.

The Viewrium API is a single JSON REST API. This page covers the conventions that apply everywhere and maps every /v1 endpoint to its SDK method. Every field of every response is on the object pages - Product, Quote, Ticket, operation results, API key, Webhook endpoint, Webhook delivery, Usage and Error - and every endpoint's parameters, request body and responses are in the generated HTTP reference. Both are built from the API's OpenAPI schema, as the typed Python and JavaScript SDKs are.

Conventions

  • Base URL - https://api.viewrium.com. Every path below is relative to it.
  • Auth - Authorization: Bearer <key> on every request. See Authentication.
  • JSON - request and response bodies are JSON. Timestamps are ISO 8601 in UTC.
  • Pagination - list endpoints take limit and offset query params and return total, limit, and offset alongside data.
  • Scope - reads take org_id (or default to your only organization) and scope=all for every organization you reach. Writes always name one.
  • Repeated params - a filter that takes several values is repeated (?tag=a&tag=b), and tag_match (all | any) says how the repeats combine.
  • Errors - every non-2xx response is the envelope { "error": { "code", "message", "details" } } (The Error object); a 422 lists each failure under details.errors.

Endpoints

Products

MethodPathSDK
POST/v1/productsproducts.create
GET/v1/productsproducts.list
GET/v1/products/{id}products.retrieve
GET/v1/products/lookup?custom_id=...products.retrieveByCustomId / retrieve_by_custom_id
PATCH/v1/products/{id}products.update
DELETE/v1/products/{id}products.delete
DELETE/v1/products?ids=a&ids=bproducts.batchDelete / batch_delete
POST/v1/products/publishproducts.publish
GET/v1/products/tagsproducts.tags
GET/v1/products/exportproducts.export
GET/v1/products/{id}/qrproducts.qr

POST /v1/products is the single entrypoint - supply exactly one of image_urls, video_url, source_url, model_url, image_paths, or resume_token. A fresh request answers 200 with a parked quote (nothing written); a resume_token or a model_url answers 202 with the created product. See How generation works. draft.painting selects the painting path, and PATCH /v1/products/{id} with painting or dimensions rebuilds a painting's model in the background - see Paintings for both and their details.reason refusals.

GET /v1/products/{id} answers two shapes by principal: a session or sk_ key gets the product with its assets, a pk_ key gets the allow-listed public projection - and only for a published product with a ready model.

Both shapes carry viewer_desktop (viewer, qr, button or hidden) and viewer_mobile (viewer, button or hidden - a phone cannot scan its own QR code), both viewer by default: how the embed shows the product. Set them with PATCH /v1/products/{id}; any other value, or null, is a 422.

GET /v1/products/lookup?custom_id=... finds a product by your own custom_id and answers exactly what GET /v1/products/{id} answers - the same two shapes, the same pk_ gate. It looks within one organization: a key's own, or for a session the org_id you pass (optional when you belong to one). A custom id not found there, or a product a pk_ key may not see, is a 404. The custom id is a query parameter rather than a path segment because it is free text and may contain /. Ticket mints take the id it answers.

GET /v1/products/export answers a ZIP of finished images - each one composited onto its background with its shadow - selected by ids or by the list's own filters, at most 200 products. image_review_status (default accepted and pending) chooses which images go in; the archive's manifest.json names every entry and every image skipped. The 3D model is never included. When more images need finishing than one request can do, the answer is a 202 with status: "queued": they are finished in the background, a download link is emailed to notify_email, and the same request then streams the ZIP.

GET /v1/products/{id}/qr answers the product's QR code as a square PNG (size 256-2048 px, default 1024; guide=true for the card with the steps). The code encodes the product's viewer_url, which GET /v1/products/{id} carries for a session or sk_ key. It is answered before the product is published too; the Viewrium-Published header says whether the link opens yet. See QR codes.

Assets and review

MethodPathSDK
PATCH/v1/products/{id}/images/{image_id}products.updateImage / update_image
PATCH/v1/products/{id}/modelproducts.updateModel / update_model
POST/v1/products/{id}/model/rescaleproducts.rescale
POST/v1/products/{id}/ticketsproducts.createTicket / create_ticket
POST/v1/products/{id}/orderproducts.order
POST/v1/products/{id}/reviewproducts.review

POST /v1/products/{id}/order orders the missing half - images onto a model-only product, or a model onto an images one. It parks like a create: commit the returned token through products.create. A 409 carries details.reason (no_analysis, generating, images_ordered, model_exists, model_failed).

POST /v1/products/{id}/review is the batched flush: image decisions and settings, the model's decision, and the product's user-set status, validated together and applied in order. It records decisions only; the finished images are made by the export.

Model tickets

No response carries a URL for a 3D model file - not the product, not a webhook, for any key. The only way to a model's bytes is a ticket: POST /v1/products/{id}/tickets with { "kind": "view" | "ar", "origin"?: string } answers { url, kind, expires_at }. The url serves the GLB (model/gltf-binary) once, until expires_at - 60 seconds for view, 30 for ar - and is never cached.

  • view is for the page that shows the model: the file streams only to a request whose Origin is the ticket's. With a publishable key that is the page's own Origin (the product must be published); with a secret key pass origin - the page that will load the model, which must be one of your allowed domains.
  • ar is for Android's Scene Viewer, which downloads the file outside the page and sends no Origin. Mint it when the shopper taps the AR button.
  • A ticket that is spent, expired or presented from the wrong origin answers 410. Minting is rate limited per IP and per product (429).

The browser that renders a model receives its bytes, so a ticket stops permanent links and hotlinking - it does not make a viewable model undownloadable.

Analytics

MethodPathSDK
GET/v1/usageusage.get
POST/v1/beaconbeacon.send

GET /v1/usage takes an arbitrary window (start / end, defaulting to the last 30 days), granularity (hour | day), an event_type filter, and a scope: one organization (org_id), every one you reach (scope=all), or one product (product_id, which needs no org_id). Organization-internal traffic is excluded unless include_internal=true.

group_by=product additionally returns by_product: the window's best-performing products, ranked by 3D views then AR entries, capped at 20, each with its title. The buckets themselves are unchanged - to break one period down, ask again with the window narrowed to it. A subject with no product row is a v1 scan: it still counts in totals, but it is never a by_product row.

POST /v1/beacon accepts a publishable (pk_) key and is what the embed uses to report view / ar_enter / ar_session_ended events.

Webhooks

MethodPathSDK
GET/v1/webhookswebhooks.list
POST/v1/webhookswebhooks.create
GET/v1/webhooks/{id}webhooks.retrieve
PATCH/v1/webhooks/{id}webhooks.update
DELETE/v1/webhooks/{id}webhooks.delete
GET/v1/webhooks/{id}/deliverieswebhooks.listDeliveries / list_deliveries

See Webhooks for the event envelope and signature scheme.

Keys

MethodPathSDK
GET/v1/api_keysapiKeys.list / api_keys.list
POST/v1/api_keysapiKeys.create / api_keys.create
DELETE/v1/api_keys/{id}apiKeys.revoke / api_keys.revoke

Some management operations - creating API keys, for example - are restricted to account owners and admins and are typically done from the dashboard.

Health

MethodPathSDK
GET/v1/healthclient.health()

Key type access

Not every endpoint accepts every key type. In particular, publishable (pk_) keys are limited to GET /v1/products/{id}, GET /v1/products/lookup, POST /v1/products/{id}/tickets and POST /v1/beacon, and are origin-gated. Everything else requires a secret (sk_) key or a signed-in dashboard session. See Authentication for the full model.

Not on the public API

Organization, team and billing management, comments, change requests, and the review app's own tooling live on an internal surface that the dashboard uses and that is deliberately not part of /v1. The Viewrium Shopify app, which will sync products from a store, is coming soon.

On this page