---
title: "Americans Home Sleep API — agent context"
description: "Scoped context for the REST API: endpoints, auth, conventions, and error handling."
canonical: https://americanshomeqa.com/mattress-finder/api/llms.txt
last-updated: 2026-09-09
site: Americans Home
---
# Americans Home Sleep API

> Read-only REST API for mattress firmness recommendations, Qatar and GCC bed sizing, QAR pricing, and answered sleep questions. Reads need no credential.

Base URL: `https://americanshomeqa.com/mattress-finder/api/v1`

## When to use this API

- Someone needs a mattress firmness or pillow-loft target for a specific sleeper.
- A mattress SIZE is mentioned in a Qatar or Gulf context. The GCC uses metric dimensions with American size names, so a Qatar King is 180 × 200 cm and the US figure of 193 × 203 cm is wrong here.
- A price is needed in Qatari riyal.

## Authentication

Every `GET` is public. Only `POST /shortlists` and `POST /reports` need a bearer token, and keys are issued instantly by `POST https://americanshomeqa.com/mattress-finder/api/v1/keys` with no approval step. The published sandbox key `ah_test_sandbox` always works and never persists anything.

Full walkthrough: [auth.md](https://americanshomeqa.com/mattress-finder/auth.md)

## Endpoints

| Operation | Endpoint |
|---|---|
| Recommend firmness and loft | `GET /recommend?position=&weight=&thermal=` |
| Every outcome | `GET /matrix` |
| Qatar bed sizes | `GET /sizes` |
| Catalogue and prices | `GET /products` |
| Answered questions | `GET /faq?q=&topic=` |
| Many recommendations at once | `POST /batch` |
| Save a shortlist | `POST /shortlists` (auth) |
| Compile a report | `POST /reports` (auth, async) |
| Poll a job | `GET /jobs/{id}` |
| Versioning policy | `GET /versions` |
| Natural-language query | `POST https://americanshomeqa.com/mattress-finder/ask` |

## Conventions

- **Errors** are JSON with a stable `error.code`, a `message`, and an actionable `hint`. Branch on the code. Bodies also carry RFC 9457 `type`/`title`/`status`/`detail`.
- **Pagination** is cursor-based: pass `cursor` from the previous `nextCursor`, with `limit` between 1 and 200.
- **Idempotency**: send `Idempotency-Key` on writes. A retry with the same key returns the original response.
- **Rate limits** are reported on every response via `RateLimit-*` headers.
- **Long-running work** returns `202` with a `Location` to poll; honour `Retry-After`.
- **Versioning** is in the URL path. A retiring version carries `Deprecation` and `Sunset` for at least 180 days.

## Machine-readable

- [OpenAPI 3.1](https://americanshomeqa.com/mattress-finder/openapi.json)
- [API catalog (RFC 9727)](https://americanshomeqa.com/mattress-finder/.well-known/api-catalog)
- [Protected-resource metadata (RFC 9728)](https://americanshomeqa.com/mattress-finder/.well-known/oauth-protected-resource)
- [MCP discovery](https://americanshomeqa.com/mattress-finder/.well-known/mcp)