Agentyk Showroom delivery API (v1)
Base URL: your Showroom host, e.g. https://showroom.example.com. All paths below start with /api/v1/{account} where {account} is your account slug (e.g. demo).
Access
- Products marked public in the Studio can be read without credentials.
- Other products need an API key of the same account: header
X-Api-Key: shr_...or query parameterkey=shr_.... A key can be restricted to your website's domains (browser requests from other origins are refused; server-to-server requests withoutOrigin/Refererare allowed). - CORS: all delivery responses carry
Access-Control-Allow-Origin: *.
Selecting options: features
Options are chosen with repeated query parameters feature=GROUP:VALUE:
?feature=UPHOLSTERY:VELVET_FOREST&feature=LEGS:WALNUT
- Codes are case-insensitive in URLs (canonical form is upper case). A comma-separated list in one parameter also works:
feature=UPHOLSTERY:VELVET_FOREST,LEGS:WALNUT. - Groups you leave out take their default value.
- An unknown group or value is an error (
400) unless you addignoreunknownfeatures=true, in which case the unknown entries are ignored (handy when a shop sends more attributes than we model). - The same group twice with different values is an error.
- Combinations excluded in the Studio ("allowed combinations") return
400.
Endpoints
Product list
GET /api/v1/{account}/products → { account, products: [{code, name, status, version}] }
Product definition
GET /api/v1/{account}/products/{PRODUCT}
Returns name, description, dimensions (mm, W x H x D), feature groups with their values (code, name, default, swatch colour), excluded combinations, the number of spin frames, the list of stills, and URL templates.
Spin frames
GET /api/v1/{account}/products/{PRODUCT}/frames/{n}/{name}.{ext}
n= 1 ... 32. Frame 1 looks at the front; frames continue clockwise seen from above (11.25° per frame).{name}is free text (use it for SEO-friendly file names); it does not affect the image.{ext}=jpg,png,webporavif.- Query:
feature=...(see above),size(longest side in px, 64-2048, default 1024),background(6-digit hex such asffffff, ortransparentfor png/webp/avif; defaultf4f3f0),wait(seconds to wait for an image that is not rendered yet, 0-60, default 25).
Example:
/api/v1/demo/products/CLUB-ARMCHAIR/frames/5/club-armchair-walnut.webp?feature=UPHOLSTERY:STRIPE_RED&feature=LEGS:WALNUT&size=800
Stills
GET /api/v1/{account}/products/{PRODUCT}/stills/{still}/{name}.{ext} with still = front, threequarter, side, back, detail (close-up of the upholstery) or dimensions (three-quarter view with width/depth/height lines). Same query parameters as frames.
3D models
GET .../products/{PRODUCT}/model.glb?feature=...— glTF 2.0 binary, meshopt-compressed geometry and KTX2 (BasisU) textures, real-world scale in metres.GET .../products/{PRODUCT}/model.usdz?feature=...— USDZ for iOS AR Quick Look.wait(0-90 s, default 45) as above.
QR code and AR page
GET .../products/{PRODUCT}/qr.svg?feature=...— SVG QR code that opens the AR page.GET /ar/{account}/{PRODUCT}?feature=...— mobile page: 3D view and "View in your room" (WebXR on Android, Quick Look on iOS).
Status (render progress)
GET .../products/{PRODUCT}/status?feature=... → { combo, key, frames: [1, 9, 17, ...], frames_total: 32, stills: [...], glb, usdz, version }. It also queues whatever is missing for that combination (add queue=0 to only look).
Analytics events (used by the viewer)
POST /api/v1/{account}/events with JSON {"product": "CODE", "event": "viewer_load" | "spin" | "zoom" | "option_change" | "ar_open" | "fullscreen"}. Stored as anonymous daily counters only.
Responses and caching
| Status | Meaning |
|---|---|
| 200 | the file (images: Cache-Control: public, max-age=3600, strong ETag; If-None-Match gives 304) |
| 400 | bad feature / size / format / background / frame number, or an excluded combination |
| 404 | unknown account or product, or a private product without a valid key |
| 409 | the product has no finished version yet |
| 503 | the combination is being rendered; JSON body, Retry-After: 10 |
Rendering is on demand: the first request for a new combination queues a high-priority job (the spin renders frames 1, 17, 9, 25, ... first). Popular combinations are pre-rendered automatically, and the Studio has "Render all combinations".
Errors are JSON: {"error": "unknown value \"PINK\" for feature group \"UPHOLSTERY\"", "detail": {...}}.