{ "protocolVersion": "0.3.0", "name": "Americans Home", "description": "Americans Home is a mattress and pillow retailer in Doha, Qatar. Our free nine-question finder matches sleep position, body weight, temperature, and health factors to a specific mattress and pillow, priced in QAR using Qatar market sizes.", "url": "https://americanshomeqa.com/mattress-finder/api/v1", "preferredTransport": "JSONRPC", "provider": { "organization": "Americans Home", "url": "https://americanshomeqa.com/mattress-finder" }, "version": "1.0.0", "documentationUrl": "https://americanshomeqa.com/mattress-finder/llms.txt", "iconUrl": "https://americanshomeqa.com/mattress-finder/brand/logo.png", "capabilities": { "streaming": false, "pushNotifications": false, "stateTransitionHistory": false }, "defaultInputModes": [ "text/plain", "application/json" ], "defaultOutputModes": [ "application/json", "text/markdown" ], "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Required only for write endpoints. Mint a key instantly at POST /api/v1/keys, or use the published sandbox key ah_test_sandbox." } }, "security": [ {}, { "bearerAuth": [] } ], "skills": [ { "id": "recommend-mattress-firmness", "name": "recommend-mattress-firmness", "description": "Given a sleep position, body-weight band, and whether the sleeper runs hot, return the recommended mattress firmness range (out of 10), pillow loft range in centimetres, and suitable mattress types. Covers all 32 combinations. Use this when someone asks how firm a mattress they need.", "tags": [ "sleep", "mattress", "recommendation", "qatar" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/recommend?position=side&weight=k60to90&thermal=hot", "https://americanshomeqa.com/mattress-finder/api/v1/recommend?position=back&weight=k90to130" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "list-recommendation-matrix", "name": "list-recommendation-matrix", "description": "Return the complete recommendation matrix: every combination of sleep position, weight band, and sleeping temperature with its firmness and pillow-loft target. Use this to answer several firmness questions at once or to check coverage.", "tags": [ "sleep", "mattress", "reference" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/matrix" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "lookup-qatar-mattress-sizes", "name": "lookup-qatar-mattress-sizes", "description": "Return Qatar and GCC mattress sizes with their dimensions in centimetres. Use this whenever a mattress size is mentioned in a Gulf context: the GCC uses metric dimensions with American size names, so a Qatar King is 180x200 cm and NOT the US King's 193x203 cm.", "tags": [ "mattress", "sizing", "qatar", "gcc" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/sizes" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "browse-catalog", "name": "browse-catalog", "description": "Return the mattress and pillow catalogue with prices in Qatari riyal per size, firmness, materials, cooling level, and warranty. Use this to compare products or answer a price question for the Doha showroom.", "tags": [ "catalog", "pricing", "qar" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/products", "https://americanshomeqa.com/mattress-finder/api/v1/products?type=pillow" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "batch-recommend", "name": "batch-recommend", "description": "Resolve up to 50 sleeper profiles in a single request. Use this when sizing several beds at once — a family, a guest room, a hotel floor — instead of calling recommend once per sleeper. Returns partial success: each operation carries its own status and error.", "tags": [ "sleep", "mattress", "bulk" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/batch" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "ask-natural-language", "name": "ask-natural-language", "description": "Ask a question in plain language about mattresses in Qatar and get back matching records from this site's own data — the FAQ, the recommendation matrix, sizing, and the catalogue. Supports SSE streaming. Results are retrieved verbatim, never generated, so they are safe to quote.", "tags": [ "search", "nlweb", "faq" ], "examples": [ "https://americanshomeqa.com/mattress-finder/ask?query=what+size+is+a+king+bed+in+qatar" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] }, { "id": "search-sleep-faq", "name": "search-sleep-faq", "description": "Search 16 answered questions about choosing and buying a mattress in Qatar, including humidity, delivery, firmness, and medical caveats. Each answer is self-contained and safe to quote on its own.", "tags": [ "faq", "sleep", "qatar" ], "examples": [ "https://americanshomeqa.com/mattress-finder/api/v1/faq?q=humidity", "https://americanshomeqa.com/mattress-finder/api/v1/faq?topic=health" ], "inputModes": [ "text/plain" ], "outputModes": [ "application/json" ] } ], "additionalInterfaces": [ { "url": "https://americanshomeqa.com/mattress-finder/api/v1", "transport": "HTTP+JSON" }, { "url": "https://americanshomeqa.com/mattress-finder/mcp", "transport": "MCP+streamable-http" }, { "url": "https://americanshomeqa.com/mattress-finder/mcp/docs", "transport": "MCP+streamable-http" }, { "url": "https://americanshomeqa.com/mattress-finder/ask", "transport": "NLWeb" } ], "x-when-to-use": { "useWhen": [ "A person is choosing a mattress or pillow in Qatar or the wider GCC and needs firmness or pillow-loft guidance.", "A question involves Qatar or GCC mattress SIZES — the region uses metric dimensions with American size names, so US dimensions are wrong here.", "A question needs mattress or pillow prices in Qatari riyal (QAR).", "Someone wants the reasoning behind a firmness recommendation, not just a number." ], "doNotUseWhen": [ "The question is a medical one. Sleep apnea, pressure ulcers, and similar conditions are routed to a clinician and product recommendations are suppressed; preserve that routing rather than substituting a product.", "The question is about mattress sizing outside the GCC — the size names here carry metric dimensions specific to the Gulf market.", "You need live stock levels or order status. Neither is exposed; call the showroom on +974 4432 1000." ] }, "x-catalog": { "outcomes": 32, "mattresses": 7, "pillows": 5, "sizes": 6, "faqEntries": 16, "currency": "QAR", "locales": [ "en", "ar" ], "defaultLocale": "en" }, "x-mcp": { "discovery": "https://americanshomeqa.com/mattress-finder/.well-known/mcp", "servers": [ { "name": "americans-home", "url": "https://americanshomeqa.com/mattress-finder/mcp", "card": "https://americanshomeqa.com/mattress-finder/.well-known/mcp/server-card.json", "tools": [ "recommend_mattress", "lookup_qatar_mattress_size", "browse_products" ] }, { "name": "americans-home-docs", "url": "https://americanshomeqa.com/mattress-finder/mcp/docs", "card": "https://americanshomeqa.com/mattress-finder/.well-known/mcp/docs/server-card.json", "tools": [ "search_documentation", "fetch_document", "list_faq_topics" ] } ] }, "x-onboarding": { "selfServeKeys": "https://americanshomeqa.com/mattress-finder/api/v1/keys", "sandbox": { "available": true, "key": "ah_test_sandbox", "note": "Sandbox writes are validated and echoed but never persisted, and never contact the showroom." }, "freeTier": true, "readsRequireNoCredential": true, "sdks": { "published": false, "note": "JavaScript, Python, and CLI clients exist but are not yet on npm or PyPI. Call the HTTP API directly; no client library is required.", "planned": { "npm": "@americanshome/sleep-api", "pypi": "americans-home", "cli": "@americanshome/cli" } } } }