Skip to content
Dials Docs

Dials API

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: <HTTP-date> (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.