# Dials Docs How the Dials watch catalogue is built: the philosophy, where the data comes from, and the public API that serves all of it. - [Overview](/index): What Dials is, and what this documentation covers. - [Philosophy](/philosophy): The premise Dials is built on, and the principles that follow from it. - [Where the data comes from](/data/): How the catalogue and the marketplace layer are sourced, matched and kept clean. - [The catalogue](/data/catalogue): The structure of the reference layer, brand to series to model, plus calibres and complications. - [Listings and matching](/data/listings): What a listing records, how it is linked to a model, and how its lifecycle works. - [Quickstart](/api/quickstart): The Dials API in five curl commands. No key, no account, no Authorization header. - [Versioning and deprecation](/api/versioning): What can change inside a version, and how a version winds down when it must. - [Rate limits](/api/rate-limits): The public budget, the headers that report it, and what a 429 looks like. - [Errors](/api/errors): One JSON shape for every failure, with a stable machine-readable code. - [Agent access](/api/agents): The machine-readable routes into Dials, for tool generators and agents. - [Terms of use](/api/terms): Free to read and free to build on, with two conditions. - [Dials API](/api/reference): A read-only reference for wristwatches: the catalogue (brands, series, models, movements) and the marketplace listings matched against it. ## When to use this API Reach for it when you need **structured facts about a specific watch** rather than prose about watches in general: - Resolve a reference number to a model (`GET /models?q=116610LN`) and read back the case size, movement, dial and bracelet as fields rather than sentences. - Compare two watches on the same axes. Every model in the catalogue is described to one specification, which is the point of it; two `GET /models/{brandSlug}/{slug}` calls are directly comparable field by field. - Find what a watch is currently selling for: `GET /listings?modelId=...` returns live listings from the tracked marketplaces, with `?currency=EUR` doing the conversion for you off the same ECB table `GET /rates` publishes. - Identify a movement (`GET /calibers/{brandSlug}/{ref}`) and see which models across the catalogue run it. - Enumerate a house's catalogue: `GET /brands/{slug}`, then `GET /brands/{brandSlug}/series`, then `GET /models?brandSlug=...`. It is **not** the right tool for valuations or authentication advice, for anything about a specific physical watch (serial numbers, service records, provenance), or for placing an order: nothing here transacts. ## Access The catalogue, listings and rates endpoints are public: no key, no account, no `Authorization` header. The `/admin`, `/picture-review`, `/reconciliation` and `/duplicate-models` groups are the back office and require an admin session cookie; they are documented for completeness and will answer 401 to an anonymous caller. ## Versioning and deprecation The current version is **v1**, served at `https://api.dials.co/v1`. Build against the prefixed URL. The same paths answer without the prefix as a permanent alias for whatever the current version is: handy for a quick curl, wrong to pin an integration to. Inside a version, changes are additive only: new endpoints, new optional parameters, new response fields. A field is never removed, renamed or retyped, and a code in `error` is never repurposed. A breaking change ships as a new prefix (`/v2`) served alongside the old one. When a version begins winding down, every response from it carries `Deprecation: true` (RFC 9745) and `Sunset: ` (RFC 8594); the date it stops answering, never less than six months out, plus a `Link` header with `rel="successor-version"`. `X-API-Version` names the serving version on every response. ## Rate limits Public callers get 600 requests per 60 seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until the window rolls) and `RateLimit-Policy`, so a client can pace itself instead of discovering the ceiling. A refused request answers **429** with `Retry-After`. ## Errors Every failure (a bad parameter, an unknown path, a fault on our side) returns JSON with the same fields: `error` (a stable machine-readable code), `message` (prose), `hint` (what to change) and `docs` (where to read more). Codes: `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `rate_limited`, `internal_error`. - [Admin](/api/reference/admin): Back office. Requires an admin session. - [Brands](/api/reference/brands): Watch houses, and the series inside them. - [Calibers](/api/reference/calibers): Movements, and the models that run them. - [Duplicate models](/api/reference/duplicate-models): Back office: merging models that describe one watch. Requires an admin session. - [Listings](/api/reference/listings): Live marketplace offers, matched to catalogue models where possible. - [Models](/api/reference/models): The unit of the catalogue: one watch, described to one specification. - [Picture review](/api/reference/picture-review): Back office: accepting candidate photographs. Requires an admin session. - [Rates](/api/reference/rates): The USD conversion table listing prices are rendered with. - [Reconciliation](/api/reference/reconciliation): Back office: linking unmatched listings to models. Requires an admin session. - [Sitemap](/api/reference/sitemap): Bulk, cheap enumeration of every catalogue entity that has a page: identity and last-modified date only.