API & MCP

One registry, two surfaces. Both take the customer's raw text and return ranked canonical models with their compatibility attributes.

Authentication

Every REST request needs an API key in the X-API-Key header. Keys are issued from the admin area; ask the registry owner for one. Keys are rate limited per minute and every call is logged so unresolved queries can be turned into new registry entries.

curl -H "X-API-Key: fk_live_…" \
  "https://<your-domain>/api/public/v1/watches/search?q=fenix7%20pro"

GET /api/public/v1/{dataset}/search

Query params: q (required, the raw consumer string) and limit (1–25, default 10). Do not pre-clean the text — normalization, aliasing and fuzzy matching happen server-side.

{
  "dataset": "watches",
  "query": "fenix7 pro",
  "count": 3,
  "ambiguous": false,
  "results": [
    {
      "slug": "garmin-fenix-7-pro",
      "canonical_name": "Garmin fenix 7 Pro",
      "brand": "Garmin",
      "case_size_mm": 47,
      "score": 0.94,
      "confidence": 0.95,
      "fitments": [
        {
          "attachment_system": "quickfit",
          "attachment_system_name": "QuickFit",
          "lug_width_mm": 22,
          "fit": "native",
          "source_url": "https://…"
        }
      ]
    }
  ]
}

When ambiguous is true the top candidates score within 0.05 of each other — the correct agent behaviour is to ask one clarifying question rather than pick the first row.

GET /api/public/v1/{dataset}/models/{slug}

Full record for one model: aliases, every fitment row, specifications, per-row confidence and source URLs.

GET /api/public/v1/datasets

Lists datasets and their attribute schemas. Today: watches (Garmin and Apple). The schema is dataset-agnostic, so other categories can be added without changing the API shape.

MCP server

Streamable HTTP endpoint at /mcp, no key needed. Add it in your assistant's connector settings and it exposes three tools: find_watch, get_watch and list_datasets.

{
  "mcpServers": {
    "fit-finder": {
      "url": "https://<your-domain>/mcp"
    }
  }
}

Guidance for agents

Pass the customer's words verbatim; the registry handles typos and nicknames.
Answer from fitments[] only. native is the designed mechanism; compatible works but is not.
Never answer strap compatibility from model memory — it is a common failure case.
A machine-readable summary of all of this lives at /llms.txt and /api/public/v1/openapi.

Where the data comes from

Every fitment carries a source_url and a verified_at timestamp. A row is only marked verified when the value was read from the manufacturer's own page for that exact watch. If we cannot confirm a value, it stays unverified rather than being guessed.

Garmin: the product page for each watch on garmin.com. The strap width is read from the specification table (QuickFit or quick-release row) and matched to the case size on the same page, e.g. /p/886785/#specs for the Forerunner 265. Discontinued watches that no longer have a product page stay unverified.
Apple: Apple states band fit by case size, not lug width — Change your Apple Watch band plus the Apple Store band compatibility chart for the 42mm case introduced with Series 10.

Errors

Errors return { "error": { "code", "message" } } with a matching status: 401 missing/invalid key, 400 invalid query, 404 unknown model, 429 rate limited.