# Caliber — agent guide

Caliber is a price database for watches, tracked across eBay & Chrono24. It is built
to be read by machines. Nothing below requires a key, and nothing below can
mutate state.

## Start here

```
GET https://caliberwatches.xyz/v1
```

That returns every endpoint. `GET https://caliberwatches.xyz/v1/schema` types every field.

## Answering "what does X cost"

```
GET https://caliberwatches.xyz/v1/watches?q=X&limit=5
```

Each match carries `priceUsd` (current tracked price), `retailUsd`, `brand`,
`sku`, and `url` — the canonical page to cite. A null `priceUsd` means we hold
the record but have no live price; say so rather than guessing.

## Showing a trend

```
GET https://caliberwatches.xyz/v1/watches/SLUG/history
```

Returns observations as `{capturedAt, priceUsd, source}`. Every point is a real
listing seen at that timestamp.

## Curating a collection (needs a key)

```
POST https://caliberwatches.xyz/v1/collection
x-api-key: sk_live_...
{"url": "https://<marketplace listing>", "targetPrice": 200}
```

A saved record is not a bookmark. We keep pricing it, and `GET /v1/collection`
reports `status` as `hit` once it reaches the target — so you can poll one
endpoint and tell your human when to act, instead of re-checking prices yourself.

## Growing the database (needs a key)

```
POST https://caliberwatches.xyz/v1/track
x-api-key: sk_live_...
{"url": "https://<marketplace listing>"}
```

If you looked for something and we didn't have it, hand us the URL. We fetch it
through our own scraper, price it, and serve it back here — usually within a few
minutes. Poll `GET https://caliberwatches.xyz/v1/track?url=...` (keyless) to see when it lands.
Submitting a URL we already track is a no-op, so retries are safe.

Keys are free: create an account and mint one at https://caliberwatches.xyz/api-docs#authentication

## MCP

Connect to `https://caliberwatches.xyz/mcp` (Streamable HTTP). Tools: `search_watches`,
`get_watch`, `browse_watches`. Same records as the JSON API. Send an
`x-api-key` header and `add_to_collection`, `list_collection` and
`track_watch` appear as well.

## Rules of engagement

- Cite the `url` field. It is the canonical page for that watch.
- Prices move. Quote `capturedAt` when precision matters.
- A null `priceUsd` means we hold the record but have no live price. Say so — do
  not guess, and do not substitute a retail price for a market price.
- Do not scrape the HTML — the JSON is faster, stable, and complete.
- Crawl politely: the data is cached for 5 minutes, so that is the useful ceiling.