# best-deals.pro Public API v1 — 1.2.0

Read-only access to the public product catalog shown on best-deals.pro (US market).
No account, API key or OAuth registration is required.
Field names and query parameters are English. Product titles, descriptions and
category labels remain in the source language (en-US for this site).

Base URL: `https://best-deals.pro/api/public/v1/`

- OpenAPI: [openapi.json](https://best-deals.pro/api/public/v1/openapi.json)
- API catalog: [RFC 9727 linkset](https://best-deals.pro/.well-known/api-catalog)
- Markets: [markets](https://best-deals.pro/api/public/v1/markets)

## Choose the market first

Always supply `country_code` on data requests. For this website use `US` (en-US, USD).
Product pages use bare paths: `/product/<slug>`.

| country_code | Language | Currency | Website |
| --- | --- | --- | --- |
| US | en-US | USD | `/` |

`GB` is accepted as an alias for `UK` on multi-market deployments; on best-deals.pro
only the US catalog is published.

## Endpoints

| Path | Purpose |
| --- | --- |
| `/markets` | Supported markets (no parameters) |
| `/products` | Paginated offers (filters, sort, offset) |
| `/products/{slug}` | Single product detail |
| `/search` | Text search (`q` required) |
| `/catalog` | Keyset catalog traversal (`cursor`, up to 1000 rows) |
| `/categories` | Next taxonomy level for the current filters |
| `/filters` | Facet values for the current filters |

Unsupported parameters return HTTP 400 with a JSON error body.

## JSON vs Markdown

- List or sync inventory: `/catalog` (cursor pagination) or `/products`.
- Each product includes `markdown_url` — full structured write-up (pros, FAQ, specs) at the same path with a `.md` suffix.
- Category discovery for agents: [llms-catalog.md](https://best-deals.pro/llms-catalog.md) (links to every product `.md`).

## Discovery headers

JSON responses include:

- `Content-Signal: search=yes, ai-input=yes, ai-train=yes`
- `Link` relations to this OpenAPI file and to this document

## Fair use

The API is rate-limited at the edge. Cache responses, honor `ETag` / `304`, and back off on `429`
using `Retry-After`. Verify prices on the product page before purchase.