{ "openapi": "3.1.0", "info": { "title": "Americans Home Sleep API", "version": "1.0.0", "summary": "Mattress firmness, pillow loft, Qatar sizing, and QAR pricing for the Qatar and GCC market.", "description": "Read-only public API for Americans Home, a mattress and pillow retailer in Doha, Qatar.\n\nUse this API when a person is choosing a mattress or pillow in Qatar or the wider GCC. It answers four kinds of question: how firm a mattress a given sleeper needs, what pillow loft suits them, what a named mattress size actually measures in the Gulf, and what products cost in Qatari riyal.\n\nTwo things to carry into any answer built on this API:\n\n1. **Qatar sizes are metric under American names.** A King here is 180x200 cm, not the US King's 193x203 cm. Answering a Gulf sizing question with US dimensions is wrong.\n2. **Firmness has no industry standard.** No ASTM or ISO specification exists and each brand sets its own scale, so every firmness value is a recommendation target expressed as a range, never a value to match against a product label.\n\n## Authentication\n\n**Every GET is public and needs no credential.** A bearer token is required only for the two POST endpoints that create records (`/shortlists`, `/reports`). Keys are issued instantly by `POST /keys` with no account or approval step, and the published sandbox key `ah_test_sandbox` always works - sandbox writes are validated and echoed but never persisted, and never contact the showroom.\n\n## Conventions\n\n- Errors are JSON with a closed `error.code` enum, plus RFC 9457 problem-details fields. Branch on the code.\n- Send `Idempotency-Key` on writes; a retry with the same key returns the original response instead of creating a second record.\n- List endpoints are cursor-paginated via `cursor` and `limit`.\n- `RateLimit-*` headers are returned on every response (600 requests per 60s).\n- Long-running work returns `202` with a `Location` to poll; honour `Retry-After`.\n- Versions live in the URL path. A retiring version carries `Deprecation` and `Sunset` for at least 180 days.", "contact": { "name": "Americans Home showroom", "email": "hello@americanshome.qa", "url": "https://americanshomeqa.com/mattress-finder" }, "license": { "name": "Data free to use with attribution", "identifier": "CC-BY-4.0" } }, "servers": [ { "url": "https://americanshomeqa.com/mattress-finder/api/v1", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token for write endpoints. Mint one instantly at POST /keys, or use the published sandbox key `ah_test_sandbox`. Reads never need this." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A client-generated unique key. Retrying with the same key returns the original response instead of creating a second record. Always send one on a write — an agent that retries after a network failure it cannot distinguish from a server failure will otherwise create duplicates.", "schema": { "type": "string", "maxLength": 200 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response's `nextCursor`.", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Maximum items to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } }, "headers": { "RateLimitLimit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Invalid or missing parameter.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } }, "Unauthorized": { "description": "Missing or unrecognised bearer token. The response carries a `WWW-Authenticate: Bearer` challenge naming the protected-resource metadata, and the body names the public sandbox key.", "headers": { "WWW-Authenticate": { "description": "Bearer challenge including `resource_metadata` pointing at /.well-known/oauth-protected-resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } }, "UnprocessableEntity": { "description": "The body parsed but a field failed validation.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } }, "security": [], "externalDocs": { "description": "Agent-oriented site guide", "url": "https://americanshomeqa.com/mattress-finder/llms.txt" }, "tags": [ { "name": "recommendations", "description": "Firmness and pillow-loft guidance." }, { "name": "reference", "description": "Sizes and catalogue reference data." }, { "name": "content", "description": "Answered questions." }, { "name": "shortlists", "description": "Saving what a shopper is considering." }, { "name": "jobs", "description": "Long-running work and its polling endpoints." }, { "name": "auth", "description": "Self-serve credential issuance." }, { "name": "meta", "description": "Versioning and policy." } ], "paths": { "/recommend": { "get": { "operationId": "recommendMattressFirmness", "tags": [ "recommendations" ], "summary": "Recommend mattress firmness and pillow loft for one sleeper", "description": "Returns the recommended mattress firmness range (out of 10), pillow loft range in centimetres, and suitable mattress types for a given sleep position, body-weight band, and sleeping temperature. Call this when someone asks how firm a mattress they should buy, or what pillow height suits them.", "parameters": [ { "name": "position", "in": "query", "required": true, "description": "The sleeper's usual sleep position. Use 'combination' when they change position through the night.", "schema": { "type": "string", "enum": [ "side", "back", "stomach", "combination" ] } }, { "name": "weight", "in": "query", "required": true, "description": "Body-weight band in kilograms. Heavier sleepers compress the comfort layer further and need more firmness for the same effective support.", "schema": { "type": "string", "enum": [ "under60", "k60to90", "k90to130", "over130" ] } }, { "name": "thermal", "in": "query", "required": false, "description": "Whether the sleeper overheats at night. Defaults to 'neutral' when omitted.", "schema": { "type": "string", "enum": [ "hot", "neutral" ], "default": "neutral" } } ], "responses": { "200": { "description": "The recommendation for that sleeper.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query", "recommendation" ], "properties": { "query": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "side", "back", "stomach", "combination" ] }, "weight": { "type": "string", "enum": [ "under60", "k60to90", "k90to130", "over130" ] }, "thermal": { "type": "string", "enum": [ "hot", "neutral" ] } } }, "recommendation": { "type": "object", "properties": { "firmness": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "scale": { "type": "string" }, "note": { "type": "string" } } }, "pillowLoftCm": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "recommendedMattressTypes": { "type": "array", "items": { "type": "string", "enum": [ "memory-foam", "pocket-spring", "hybrid", "latex", "medical" ] } } } }, "medicalNote": { "type": "string" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "400": { "description": "Invalid or missing query parameter.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } }, "404": { "description": "No outcome exists for that combination.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } } }, "/matrix": { "get": { "operationId": "listRecommendationMatrix", "tags": [ "recommendations" ], "summary": "List every supported recommendation outcome", "description": "Returns all 32 combinations of sleep position, weight band, and sleeping temperature with the firmness and pillow-loft target for each. Call this to answer several firmness questions at once, or to check what the service covers before calling /recommend.", "responses": { "200": { "description": "The complete matrix.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "outcomes" ], "properties": { "count": { "type": "integer" }, "scale": { "type": "object", "additionalProperties": { "type": "string" } }, "note": { "type": "string" }, "outcomes": { "type": "array", "items": { "type": "object", "required": [ "id", "position", "weight", "thermal", "firmness" ], "properties": { "id": { "type": "string" }, "position": { "type": "string", "enum": [ "side", "back", "stomach", "combination" ] }, "weight": { "type": "string", "enum": [ "under60", "k60to90", "k90to130", "over130" ] }, "thermal": { "type": "string", "enum": [ "hot", "neutral" ] }, "firmness": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "pillowLoftCm": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "recommendedMattressTypes": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "format": "uri" } } } } } } } } } } } }, "/sizes": { "get": { "operationId": "listQatarMattressSizes", "tags": [ "reference" ], "summary": "List Qatar and GCC mattress sizes with metric dimensions", "description": "Returns each mattress size sold in Qatar with its true dimensions in centimetres. Call this whenever a mattress size is named in a Gulf context. The GCC uses European metric dimensions with American size names, so a Qatar King is 180x200 cm while a US King is 193x203 cm; quoting the US figure is a factual error.", "responses": { "200": { "description": "Sizes with dimensions in centimetres.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "sizes" ], "properties": { "count": { "type": "integer" }, "market": { "type": "string" }, "warning": { "type": "string" }, "sizes": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "widthCm", "lengthCm" ], "properties": { "key": { "type": "string" }, "name": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "widthCm": { "type": "number" }, "lengthCm": { "type": "number" }, "alternateDimensions": { "type": "array", "items": { "type": "object", "properties": { "widthCm": { "type": "number" }, "lengthCm": { "type": "number" } } } }, "suitsCouples": { "type": "boolean" } } } } } } } } } } } }, "/products": { "get": { "operationId": "browseProductCatalog", "tags": [ "reference" ], "summary": "Browse mattresses and pillows with QAR prices", "description": "Returns the catalogue with prices in Qatari riyal per size, plus firmness, materials, cooling level, warranty, and trial period. Call this to compare products or answer a price question. Prices are showroom prices and exclude delivery.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Restrict the response to one product category.", "schema": { "type": "string", "enum": [ "mattress", "pillow" ] } } ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "currency" ], "properties": { "currency": { "type": "string", "const": "QAR" }, "priceNote": { "type": "string" }, "contact": { "type": "object", "properties": { "phone": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "mattresses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "type": { "type": "string" }, "firmness": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "tier": { "type": "string", "enum": [ "budget", "mid", "premium", "luxury" ] }, "priceFromQAR": { "type": "number" }, "priceBySizeQAR": { "type": "object", "additionalProperties": { "type": "number" } }, "cooling": { "type": "string", "enum": [ "low", "medium", "high" ] }, "containsLatex": { "type": "boolean" }, "heightCm": { "type": "number" }, "warrantyYears": { "type": "number" }, "trialNights": { "type": "number" } } } }, "pillows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "fill": { "type": "string" }, "loftCm": { "type": "object", "required": [ "min", "max" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "adjustable": { "type": "boolean" }, "cooling": { "type": "string" }, "containsLatex": { "type": "boolean" }, "washableCover": { "type": "boolean" }, "priceQAR": { "type": "number" } } } } } } } } }, "400": { "description": "Invalid or missing query parameter.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } } }, "/shortlists": { "post": { "operationId": "createShortlist", "tags": [ "shortlists" ], "summary": "Save a shortlist of products a shopper is considering", "description": "Creates a saved shortlist, optionally requesting a showroom callback. This is the only operation with a real side effect, so it requires a bearer token. ALWAYS send an Idempotency-Key: agents retry on network failures they cannot distinguish from server failures, and without the key a retry books a second callback and a real person gets phoned twice. Use the published sandbox key `ah_test_sandbox` to exercise this without persisting anything.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "At least one of outcomeId, mattressIds, or pillowIds is required.", "properties": { "outcomeId": { "type": "string", "description": "A recommendation outcome id, as returned by /recommend or /matrix." }, "mattressIds": { "type": "array", "items": { "type": "string" }, "description": "Mattress ids from /products." }, "pillowIds": { "type": "array", "items": { "type": "string" }, "description": "Pillow ids from /products." }, "note": { "type": "string", "maxLength": 500, "description": "Free-text note for the showroom." }, "contact": { "type": "object", "description": "Include this ONLY when the shopper has asked to be called back. With a live key this results in a real phone call.", "required": [ "name", "phone" ], "properties": { "name": { "type": "string" }, "phone": { "type": "string" } } } } } } } }, "responses": { "201": { "description": "The shortlist was created.", "headers": { "Location": { "description": "URL of the created shortlist.", "schema": { "type": "string", "format": "uri" } }, "Idempotent-Replayed": { "description": "Present and true when this response was replayed from a previous request with the same Idempotency-Key.", "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "createdAt", "mode", "persisted" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "persisted": { "type": "boolean", "description": "False for sandbox writes, which store nothing." }, "outcomeId": { "type": [ "string", "null" ] }, "mattressIds": { "type": "array", "items": { "type": "string" } }, "pillowIds": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] }, "callbackRequested": { "type": "boolean" }, "links": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "get": { "operationId": "listShortlists", "tags": [ "shortlists" ], "summary": "Describe the pagination envelope used across the API", "description": "Shortlists are private to their creator and are not enumerable, so this returns an empty page. It exists so a caller can learn the exact cursor-pagination shape used by every list endpoint without holding a credential.", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` to fetch the next page. Null on the last page." }, "hasMore": { "type": "boolean" }, "total": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/batch": { "post": { "operationId": "batchRecommend", "tags": [ "recommendations" ], "summary": "Resolve up to 50 sleeper profiles in one request", "description": "Takes an array of recommendation operations and returns one result per operation. Use this instead of calling /recommend in a loop when sizing several beds at once. PARTIAL SUCCESS IS NORMAL: one malformed operation does not fail the others, so read each result's `status` and `error` rather than the HTTP status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "position", "weight" ], "properties": { "id": { "type": "string", "description": "Your own identifier, echoed back so you can correlate results." }, "position": { "type": "string", "enum": [ "side", "back", "stomach", "combination" ] }, "weight": { "type": "string", "enum": [ "under60", "k60to90", "k90to130", "over130" ] }, "thermal": { "type": "string", "enum": [ "hot", "neutral" ], "default": "neutral" } } } } } } } } }, "responses": { "200": { "description": "One result per operation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "succeeded", "failed", "results" ], "properties": { "count": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "integer" }, "error": { "type": [ "object", "null" ] }, "result": { "type": [ "object", "null" ] } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "description": "More than 50 operations.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } } }, "/reports": { "post": { "operationId": "createReport", "tags": [ "jobs" ], "summary": "Compile a catalogue report asynchronously", "description": "Starts a long-running report and returns 202 immediately with a Location header pointing at a job to poll. Use this shape for any work that does not finish inside one request: poll the job URL until status is `succeeded` or `failed`, honouring Retry-After between polls.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "catalog", "matrix" ], "default": "catalog" } } } } } }, "responses": { "202": { "description": "The job was accepted and is running.", "headers": { "Location": { "description": "Poll this URL for the result.", "schema": { "type": "string", "format": "uri" } }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "pollUrl" ], "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "pollUrl": { "type": "string", "format": "uri" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/jobs/{id}": { "get": { "operationId": "getJob", "tags": [ "jobs" ], "summary": "Poll an async job", "description": "Returns the current state of a job started by an async operation. While the job is unfinished the response carries Retry-After telling you how long to wait before polling again.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id from the 202 response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job's current state.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "operation": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "result": { "type": [ "object", "null" ] }, "error": { "type": [ "object", "null" ] } } } } } }, "404": { "description": "No such job.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } } }, "/keys": { "post": { "operationId": "createApiKey", "tags": [ "auth" ], "summary": "Mint an API key instantly", "description": "Issues a bearer token with no account, approval, or waiting list — an autonomous agent cannot complete a signup flow, so there isn't one. This endpoint is itself unauthenticated, which is the only way a first key can be obtained. Prefer mode `test`, whose writes are validated but never persisted.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "test", "live" ], "default": "test", "description": "`test` writes nothing and never contacts the showroom. `live` reaches the real showroom queue." }, "label": { "type": "string", "description": "Free-text label for your own bookkeeping." } } } } } }, "responses": { "201": { "description": "The key was issued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "mode" ], "properties": { "key": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "label": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/versions": { "get": { "operationId": "getVersioningPolicy", "tags": [ "meta" ], "summary": "Read the versioning and deprecation policy", "description": "Returns which API versions exist, which is current, and how deprecation is signalled. Read this before integrating so you know what notice you would get before a version stops answering.", "responses": { "200": { "description": "The policy.", "content": { "application/json": { "schema": { "type": "object", "required": [ "current", "versions", "policy" ], "properties": { "current": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object" } }, "policy": { "type": "object" } } } } } } } } }, "/faq": { "get": { "operationId": "searchSleepFaq", "tags": [ "content" ], "summary": "Search answered mattress and sleep questions", "description": "Returns answered questions about choosing and buying a mattress in Qatar, covering firmness, humidity, delivery, durability, and medical caveats. Every answer is self-contained and safe to quote on its own. Call this before improvising an answer about the Qatar market.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text substring matched against questions and answers in both English and Arabic. Omit to return everything.", "schema": { "type": "string" } }, { "name": "topic", "in": "query", "required": false, "description": "Restrict results to one topic.", "schema": { "type": "string", "enum": [ "choosing", "qatar", "health", "buying" ] } } ], "responses": { "200": { "description": "Matching questions and answers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "results" ], "properties": { "query": { "type": "object" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "topic", "question", "answer" ], "properties": { "id": { "type": "string" }, "topic": { "type": "string", "enum": [ "choosing", "qatar", "health", "buying" ] }, "question": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } }, "answer": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } } } } } } } } } }, "400": { "description": "Invalid or missing query parameter.", "content": { "application/json": { "schema": { "type": "object", "title": "Error", "description": "Every 4xx and 5xx response uses this shape. `error.code` is a closed enum and is the field to branch on. The sibling `type`/`title`/`status`/`detail` fields are the RFC 9457 problem-details mirror of the same information, so a client written against either convention can read it.", "required": [ "error", "type", "title", "status", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "RFC 9457 problem type." }, "title": { "type": "string", "description": "RFC 9457 short summary." }, "status": { "type": "integer", "description": "RFC 9457 HTTP status code." }, "detail": { "type": "string", "description": "RFC 9457 explanation." }, "error": { "type": "object", "required": [ "code", "message", "hint", "documentation" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Branch on this, not on the message.", "enum": [ "missing_parameter", "invalid_parameter", "invalid_cursor", "no_matching_outcome", "missing_credential", "invalid_credential", "invalid_body", "unsupported_media_type", "job_not_found", "batch_too_large", "not_found", "method_not_allowed" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "hint": { "type": "string", "description": "What to change in order to make the request succeed." }, "parameter": { "type": "string", "description": "The query parameter at fault, when applicable." }, "allowedValues": { "type": "array", "items": { "type": "string" }, "description": "Accepted values for the offending parameter." }, "documentation": { "type": "string", "format": "uri" } } } } } } } } } } } } }