{"openapi":"3.0.3","info":{"title":"Placera Proxy API","description":"Proxy API for IKEA product data (SIK), Digital Asset Management (DAM) images, selling range details, product categorisation, and 3D models (Dimma). Designed for Figma Make prototypes, GitHub Copilot, Claude Code, and other AI-assisted design tools.","version":"1.0.0"},"servers":[{"url":"https://placera-429898511304.europe-west1.run.app","description":"Production (Cloud Run)"},{"url":"http://localhost:8080","description":"Local development"}],"paths":{"/products":{"get":{"operationId":"searchProducts","summary":"Search IKEA products","description":"Search products by keyword, category, or product IDs. Returns product details including name, price, images, availability, and article numbers.","parameters":[{"name":"pageType","in":"query","schema":{"type":"string","enum":["search-result-page","product-list-page","product-group-page","visual-search-result-page","special","search-box"],"default":"search-result-page"}},{"name":"market","in":"query","schema":{"type":"string","default":"gb"},"description":"IKEA market/country code"},{"name":"language","in":"query","schema":{"type":"string","default":"en"},"description":"Language code"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query text"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category ID for product-list-page"},{"name":"products","in":"query","schema":{"type":"string"},"description":"Comma-separated product IDs for visual-search-result-page"},{"name":"contentType","in":"query","schema":{"type":"string","enum":["products","filters","categories","content"],"default":"products"}},{"name":"filters","in":"query","schema":{"type":"string"},"description":"Filter query string"},{"name":"sort","in":"query","schema":{"type":"string"},"description":"Sort order, e.g. PRICE_LOW_TO_HIGH"},{"name":"size","in":"query","schema":{"type":"string"},"description":"Number of results per page"},{"name":"store","in":"query","schema":{"type":"string"},"description":"Store ID for availability"},{"name":"zip","in":"query","schema":{"type":"string"},"description":"Zip/postal code for delivery availability"}],"responses":{"200":{"description":"Product search results","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"metaData":{"$ref":"#/components/schemas/MetaData"}}}}}}}}}}},"/selling-range":{"get":{"operationId":"getSellingRange","summary":"Get detailed product information","description":"Returns media, designers, benefits, assembly info, and package measurements for a specific item number.","parameters":[{"name":"itemNos","in":"query","required":true,"schema":{"type":"string"},"description":"IKEA article/item number"},{"name":"ru","in":"query","schema":{"type":"string","default":"US"},"description":"Retail unit / country code"},{"name":"language","in":"query","schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"Selling range data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellingRange"}}}}}}},"/categorisation":{"get":{"operationId":"getCategorisation","summary":"Get product category tree","description":"Returns a nested hierarchy of IKEA product categories with names, IDs, and images.","parameters":[{"name":"ru","in":"query","schema":{"type":"string","default":"IN"},"description":"Country code"},{"name":"language","in":"query","schema":{"type":"string","default":"en"}},{"name":"identifier","in":"query","schema":{"type":"string","default":"products"}}],"responses":{"200":{"description":"Category tree","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}},"/dam":{"get":{"operationId":"searchDAM","summary":"Search DAM images","description":"Search IKEA Digital Asset Management for product and lifestyle images.","parameters":[{"name":"searchTerm","in":"query","required":true,"schema":{"type":"string"},"description":"Search term, e.g. 'kitchen', 'KALLAX'"},{"name":"market","in":"query","schema":{"type":"string","default":"gb"}},{"name":"isProduct","in":"query","schema":{"type":"string","default":"false"},"description":"Set to 'true' to search by item number"},{"name":"isShoppable","in":"query","schema":{"type":"string","default":"1"},"description":"'1' for shoppable, '0' for all"},{"name":"limit","in":"query","schema":{"type":"string","default":"10"}},{"name":"offset","in":"query","schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"DAM search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DAMSearchResult"}}}}}}},"/dam-random-image":{"get":{"operationId":"getRandomDAMImage","summary":"Get a random DAM image","description":"Returns a random IKEA lifestyle/product image as a JPEG binary. Useful for hero banners and backgrounds.","parameters":[{"name":"searchTerm","in":"query","required":true,"schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string","default":"gb"}},{"name":"isShoppable","in":"query","schema":{"type":"string","default":"1"}},{"name":"isProduct","in":"query","schema":{"type":"string","default":"false"}},{"name":"seed","in":"query","schema":{"type":"string"},"description":"Seed for reproducible selection"},{"name":"width","in":"query","schema":{"type":"string"},"description":"Resize width in pixels"}],"responses":{"200":{"description":"JPEG image binary","headers":{"X-Image-Seed":{"schema":{"type":"string"}}},"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}}}}},"/get-dimma-list":{"get":{"operationId":"listDimmaModels","summary":"List available 3D models","description":"Returns available IKEA 3D models with product names, global IDs, and model formats.","responses":{"200":{"description":"List of 3D models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DimmaProduct"}}}}}}}},"/get-dimma-tags":{"get":{"operationId":"listDimmaTags","summary":"List available 3D model tags","description":"Returns all tags available in the Dimma system for filtering 3D models.","responses":{"200":{"description":"List of tag strings","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"},"example":["sofa","bed","storage"]}}}},"500":{"description":"Error fetching tags from upstream Dimma API"}}}},"/get-dimma-model":{"get":{"operationId":"getDimmaModel","summary":"Download a 3D model by URL","description":"Proxies and downloads a GLB 3D model file from a given upstream URL. Useful for bypassing CORS restrictions in browser-based tools such as Figma Make. The URL must use the `https` scheme and its hostname must belong to an Ingka-owned domain (e.g. `*.ingka.dev` or `*.ingka.com`). IP addresses and non-Ingka hosts are rejected.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"Full `https` URL of the GLB model file to proxy. Must resolve to an allowlisted Ingka domain."}],"responses":{"200":{"description":"GLB model binary","content":{"model/gltf-binary":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing URL parameter, non-https scheme, IP address, or host not in the allowlist"},"500":{"description":"Error fetching model from upstream URL"}}}},"/get-dimma-by-id":{"get":{"operationId":"getDimmaById","summary":"Download a 3D model by ID","description":"Returns a GLB binary file for the specified product ID.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"},"description":"Product global ID"}],"responses":{"200":{"description":"GLB model binary","content":{"model/gltf-binary":{"schema":{"type":"string","format":"binary"}}}}}}},"/showroom":{"get":{"operationId":"getShowroom","summary":"Embed an interactive 3D product showroom","description":"Returns an HTML page containing an interactive 3D IKEA product viewer built with React Three Fiber. Intended to be embedded as an iframe in prototypes and web pages. Products are placed via product{N} query parameters. Runtime control (camera, lighting, visibility, etc.) is possible via the window.postMessage API — see the full postMessage reference at the /embed section of the homepage.","parameters":[{"name":"product{N}","in":"query","description":"Product to display. N is a 0-based index (product0, product1, …). Value is a JSON object: { \"id\": \"<IKEA product ID>\", \"name\": \"optional label\", \"position\": [x, y, z], \"rotation\": [x, y, z] }. Example: product0={\"id\":\"60555153\",\"position\":[0,0,0]}","schema":{"type":"string"}},{"name":"showRoom","in":"query","description":"Show the room walls and floor.","schema":{"type":"boolean","default":true}},{"name":"style","in":"query","description":"Room style preset.","schema":{"type":"string","enum":["style1","style2"],"default":"style1"}},{"name":"backgroundColor","in":"query","description":"Background colour as a hex string (e.g. #e8e5dd). Visible when showRoom=false.","schema":{"type":"string","default":"#e8e5dd"}},{"name":"transparentBackground","in":"query","description":"Transparent canvas — set allowtransparency=\"true\" on the iframe element.","schema":{"type":"boolean","default":false}},{"name":"lightOn","in":"query","description":"Toggle the room light bulb.","schema":{"type":"boolean","default":false}},{"name":"bulbTemperature","in":"query","description":"Light colour temperature in Kelvin (2000–8000).","schema":{"type":"integer","default":5000}},{"name":"bulbLumens","in":"query","description":"Light brightness (1–100).","schema":{"type":"integer","default":10}},{"name":"physics","in":"query","description":"Enable physics simulation.","schema":{"type":"boolean","default":false}},{"name":"cameraPosition","in":"query","description":"Camera position as comma-separated x,y,z floats (e.g. 0,0.75,3.5).","schema":{"type":"string","default":"0,0.75,3.5"}},{"name":"cameraTarget","in":"query","description":"Camera look-at target as comma-separated x,y,z floats (e.g. 0,0.75,0).","schema":{"type":"string","default":"0,0.75,0"}},{"name":"cameraFov","in":"query","description":"Camera field of view in degrees.","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"HTML page containing the 3D showroom viewer.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/analytics":{"get":{"operationId":"getAnalytics","summary":"Get API usage statistics","description":"Returns aggregated usage statistics for all API endpoints, including request counts, result counts, empty-result rates, and retry counts.","parameters":[{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter statistics by source identifier"}],"responses":{"200":{"description":"Usage statistics object","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenAPISpec","summary":"Get this OpenAPI specification","responses":{"200":{"description":"OpenAPI 3.0 JSON spec"}}}}},"components":{"schemas":{"Product":{"type":"object","properties":{"name":{"type":"string"},"typeName":{"type":"string"},"productDescription":{"type":"string"},"mainImageUrl":{"type":"string"},"contextualImageUrl":{"type":"string"},"itemNo":{"type":"string"},"itemNoGlobal":{"type":"string"},"salesPrice":{"type":"object","properties":{"current":{"type":"object","properties":{"prefix":{"type":"string"},"wholeNumber":{"type":"string"},"separator":{"type":"string"},"decimals":{"type":"string"},"suffix":{"type":"string"}}},"previous":{"type":"object","nullable":true},"offerMessage":{"type":"string","nullable":true}}},"ratingValue":{"type":"string","nullable":true},"ratingCount":{"type":"string","nullable":true},"homeDelivery":{"type":"object","properties":{"text":{"type":"string"},"status":{"type":"string"}}},"cashAndCarry":{"type":"object","properties":{"text":{"type":"string"},"status":{"type":"string"}}},"media":{"type":"array","items":{"type":"object","properties":{"typeName":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"},"quality":{"type":"string"}}}}}}}}},"MetaData":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"},"max":{"type":"integer"},"moreToken":{"type":"string"},"category":{"type":"object","properties":{"name":{"type":"string"},"key":{"type":"string"},"url":{"type":"string"},"imageUrl":{"type":"string"}}}}},"SellingRange":{"type":"object","properties":{"media":{"type":"array","items":{"type":"object","properties":{"typeName":{"type":"string"},"variants":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"quality":{"type":"string"}}}}}}},"designers":{"type":"array"},"benefits":{"type":"array"},"goodToKnows":{"type":"array"},"benefitSummary":{"type":"string","nullable":true},"assemblyEffort":{"type":"object","nullable":true},"packageMeasurements":{"type":"array"},"pipImages":{"type":"array","description":"PIP media items in the original order returned by the IKEA SIK API. The `type` field reflects IKEA's typeName naming convention (e.g. \"CONTEXT_IMAGE\", \"FUNCTIONAL_DETAIL\", \"MAIN_PRODUCT_IMAGE\"). Use the `type` value as the Figma layer name for consistent automated image filling.","items":{"type":"object","properties":{"altText":{"type":"string","nullable":true},"type":{"type":"string","description":"IKEA typeName (e.g. \"MAIN_PRODUCT_IMAGE\", \"CONTEXT_IMAGE\", \"FUNCTIONAL_DETAIL\"). Order mirrors the upstream API; use as Figma layer name."},"url":{"type":"string","nullable":true}}}}}},"Category":{"type":"object","properties":{"categoryId":{"type":"string"},"categoryName":{"type":"string"},"categoryType":{"type":"string"},"image":{"type":"string","nullable":true},"productImage":{"type":"string","nullable":true},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"DAMSearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"altText":{"type":"string","nullable":true},"original":{"type":"string"},"thumbnails":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"}}}},"coordinates":{"type":"array"},"FY":{"type":"string","nullable":true},"releaseDate":{"type":"string"},"datePublished":{"type":"string"}}}},"total":{"oneOf":[{"type":"integer"},{"type":"object","properties":{"value":{"type":"integer"},"relation":{"type":"string"}}}]}}},"DimmaProduct":{"type":"object","properties":{"productName":{"type":"string"},"typeName":{"type":"string"},"globalId":{"type":"string"},"localIds":{"type":"array","items":{"type":"string"}},"models":{"type":"array","items":{"type":"object","properties":{"uri":{"type":"string"},"assetFormat":{"type":"string"},"quality":{"type":"string"}}}}}},"ProblemDetail":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"}}}}}}