Developers & AI agents

Overview

Breeza publishes a small, public, read-only API over its cooling-sleep catalog and customer reviews, plus a set of machine-readable resources so AI assistants and automated clients can discover, search, and cite the store reliably. Everything on this page is same-origin, needs no API key, and never modifies cart, checkout, or account state — those flows require a human shopper.

Authentication

None. The endpoints below are public and read-only, so no key or token is required. They are rate-limited per client IP; write operations (cart, checkout, account) are not part of this contract and are intentionally excluded.

Rate limits

Every response carries RFC 9331 rate-limit headers so a client can self-throttle without probing for 429s. On HTTP 429 a Retry-After (seconds) is also sent — back off for that long before retrying.

RateLimit-Limit: 30
RateLimit-Remaining: 28
RateLimit-Reset: 42
RateLimit-Policy: 30;w=60

Error format

Errors are structured JSON — never an HTML page — with a stable machine-readable code, a human message, and, where useful, a hint for recovery.

{
  "error": {
    "code": "invalid_request",
    "message": "product_id required",
    "hint": "Pass a valid Medusa product id, e.g. ?product_id=prod_123."
  },
  "message": "product_id required"
}

Codes: rate_limited, invalid_request, not_found, method_not_allowed, upstream_unavailable.

Markdown content negotiation

Request any page with Accept: text/markdown and the store returns a concise Markdown representation (with a canonical link back to the HTML) instead of the full page, following the acceptmarkdown.com convention.

curl -H "Accept: text/markdown" "https://www.breezasleep.com/zh/about"

In-browser tools (WebMCP)

When an agentic browser loads the storefront, a read-only search_products tool is registered on navigator.modelContext, letting an in-page agent query the catalog through the same public search surface.