Agentyk Showroom

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

Selecting options: features

Options are chosen with repeated query parameters feature=GROUP:VALUE:

?feature=UPHOLSTERY:VELVET_FOREST&feature=LEGS:WALNUT

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}

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

QR code and AR page

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

StatusMeaning
200the file (images: Cache-Control: public, max-age=3600, strong ETag; If-None-Match gives 304)
400bad feature / size / format / background / frame number, or an excluded combination
404unknown account or product, or a private product without a valid key
409the product has no finished version yet
503the 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": {...}}.