Skip to content
Luxury mattresses without luxury price tags.
Americans Home
العربية

Americans Home developer portal

A public REST API, two MCP servers, and a natural-language endpoint over the same data this site renders: mattress firmness targets, Qatar and GCC bed dimensions, and prices in Qatari riyal.

Reads need no credential. There is no signup, no API key, and no rate-limit tier for reading. Copy the line below and run it.

Quickstart

How firm a mattress does a side sleeper in the 60–90 kg band who sleeps hot need?

curl 'https://americanshomeqa.com/mattress-finder/api/v1/recommend?position=side&weight=k60to90&thermal=hot'

Write something

Writes take a bearer token. The sandbox key below is published and always valid — sandbox writes are fully validated but never persisted, and never contact the showroom.

curl -X POST https://americanshomeqa.com/mattress-finder/api/v1/shortlists \
  -H 'Authorization: Bearer ah_test_sandbox' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-unique-key-1' \
  -d '{"outcomeId":"side-sleeper-sleeps-hot-60-90kg"}'

Get your own key

Issued instantly. No account, no approval, no waiting list — an autonomous agent cannot complete a “contact sales” form, so there isn’t one.

curl -X POST https://americanshomeqa.com/mattress-finder/api/v1/keys \
  -H 'Content-Type: application/json' \
  -d '{"mode":"test","label":"my agent"}'

Endpoints

OperationEndpointWhat it does
recommend-mattress-firmnessGET /api/v1/recommendGiven 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.
list-recommendation-matrixGET /api/v1/matrixReturn 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.
lookup-qatar-mattress-sizesGET /api/v1/sizesReturn 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.
browse-catalogGET /api/v1/productsReturn 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.
batch-recommendGET /api/v1/batchResolve 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.
ask-natural-languageGET /askAsk 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.
search-sleep-faqGET /api/v1/faqSearch 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.
createShortlistPOST /api/v1/shortlistsSave a set of products a shopper is considering, optionally requesting a showroom callback. Requires a bearer token and accepts Idempotency-Key.
batchRecommendPOST /api/v1/batchResolve up to 50 sleeper profiles in one request. Partial success: each operation carries its own status.
askPOST /askNatural-language query (NLWeb), with SSE streaming via prefer: streaming=true. Returns retrieved records, never generated text.

MCP servers

Two Model Context Protocol servers over streamable HTTP, no auth. One for acting, one for reading the docs.

americanshomeqa.com/mattress-finder/mcp

Mattress firmness and pillow-loft recommendations, Qatar and GCC bed sizing, and catalogue pricing in Qatari riyal.

  • recommend_mattress
  • lookup_qatar_mattress_size
  • browse_products

americanshomeqa.com/mattress-finder/mcp/docs

Search and fetch the Americans Home documentation: the FAQ, the recommendation matrix, Qatar sizing, and pricing.

  • search_documentation
  • fetch_document
  • list_faq_topics

Conventions

Errors
JSON, always. Branch on error.code, never the message. Bodies also carry RFC 9457 problem-details fields.
Pagination
Cursor-based. Pass cursor from the previous response’s nextCursor, and limit between 1 and 200.
Idempotency
Send Idempotency-Key on every write. A retry with the same key returns the original response rather than creating a second record.
Rate limits
600 requests per 60s, reported on every response via RateLimit-* headers so you never have to probe for the ceiling.
Versioning
Versions live in the URL path. A retiring version carries Deprecation and Sunset headers for at least 180 days first.
Long-running work
Returns 202 with a Location pointing at a job to poll. Honour Retry-After.

Machine-readable