# WatchPatrol - Full Documentation for AI Agents

> Community-powered watch search engine aggregating listings from watch enthusiast forums worldwide.

## Overview

WatchPatrol is a search engine that aggregates watch listings from popular enthusiast forums and communities. We help users discover pre-owned, vintage, and new watches for sale, compare prices, and research seller reputation.

## Site Structure

### Main Sections

1. **Search/Browse** (`/`)
   - Default view shows latest listings
   - Supports filtering by query, brand, seller, source, date range, price
   - Grid and masonry view options

2. **Discover** (`/discover/`)
   - Top brands and popular watches
   - Price tier categories (under $500, $1000, $2500, $5000, over $5000)
   - Regional categories (Swiss, German, Japanese, American watches)
   - Type categories (dive watches, dress watches, chronographs)

3. **Brand Pages** (`/discover/brands/{slug}/`)
   - Brand information (established date, origin country, description)
   - Most popular models for the brand
   - Top sellers for the brand
   - Price statistics

4. **Listing Details** (`/listing/{id}/`)
   - Full listing description and images
   - Price analysis vs market median
   - Seller feedback and reputation
   - Related watches

5. **Integrations Portal** (`/integrations/`)
   - Create and revoke Personal Access Tokens
   - Manage OAuth connected apps

## Programmatic Access

WatchPatrol exposes its catalog and market data through two interfaces with distinct auth flows.

### REST API

- Base URL: `https://www.watchpatrol.net/api/public/v1/`
- Interactive docs: `/api/public/v1/docs/` (Scalar, try endpoints in-browser)
- OpenAPI 3 schema: `/api/public/v1/schema/`
- Auth: Personal Access Token (`wpat_...`) issued from `/integrations/api-keys/`, passed as `Authorization: Bearer <token>`. Commercial tier required for the REST API.

### MCP Server

- Endpoint: `https://api.watchpatrol.net/mcp/`
- Transport: Streamable HTTP
- 19 tools across catalog, pricing, listings, sellers, and identify
- Auth: OAuth 2.0 with Dynamic Client Registration (RFC 7591). Unauthenticated requests return `HTTP 401` with `WWW-Authenticate: Bearer realm="WatchPatrol", resource_metadata=<url>` (RFC 9728). Spec-compliant MCP clients discover and complete the authorization-code + PKCE flow themselves on first connect — no manual token paste.
- Verified clients: **ChatGPT** (Plus/Pro/Business/Enterprise/Edu custom connectors), **Claude Code** CLI, **Claude Desktop** (via the `mcp-remote` stdio bridge), **Gemini CLI**, **Cursor**. Free with any WatchPatrol account; paid tiers raise the rate limits.
- Discovery endpoints: `/.well-known/oauth-protected-resource` (RFC 9728), `/.well-known/oauth-authorization-server` (RFC 8414), dynamic client registration at `/oauth/register/`.

## Authentication

Two paths, picked by interface:

- **REST**: Personal Access Token (`wpat_...`) from `/integrations/api-keys/`. Header: `Authorization: Bearer {token}`. Intended for scripts, notebooks, and server-to-server integrations.
- **MCP**: OAuth 2.0 authorization-code + PKCE, negotiated by the client. OAuth-granted tokens are prefixed `wpat_oauth_...` and stored by the client (e.g. `~/.mcp-auth/` for `mcp-remote`). Browser-based interactive sign-in on first connect.
- Access is gated by the account's subscription tier for REST only — **Commercial** is required. The MCP server is free with any WatchPatrol account; paid tiers raise the rate limits.

## REST Endpoints

### Catalog (commercial tier)

```
GET /api/public/v1/brands/
GET /api/public/v1/brands/{slug}/
GET /api/public/v1/brands/{slug}/models/
GET /api/public/v1/models/
GET /api/public/v1/models/{brand_slug}/{model_slug}/
```

Returns brand and model catalog data with listing counts and aggregate price stats.

### Listings (commercial tier)

```
GET /api/public/v1/listings/
GET /api/public/v1/listings/{id}/
```

Search and retrieve individual watch listings. Supports filtering by query, brand, model, seller, source, currency, price range, and date range.

### Pricing (commercial tier)

```
GET /api/public/v1/models/{brand_slug}/{model_slug}/pricing/
GET /api/public/v1/models/{brand_slug}/{model_slug}/price-history/
```

Returns market price statistics (median, Q1, Q3, sample size) and historical price trends for a specific model.

### Sellers (commercial tier)

```
GET /api/public/v1/sellers/{username}/
```

Returns reputation evaluation, feedback counts, sentiment breakdown, and recent transactions for a seller.

### Identify (commercial tier)

```
POST /api/public/v1/identify/
```

Identifies a watch brand and model from a free-text description or image.

For full request/response schemas, parameters, and examples, see the interactive docs at `/api/public/v1/docs/` or the machine-readable schema at `/api/public/v1/schema/`.

## Rate Limits

Throttling is per-user and tier-dependent, shared across REST and MCP. Respect the `Retry-After` header on 429 responses. The interactive docs at `/api/public/v1/docs/` reflect current limits.

## Terms of Use

Full terms: https://www.watchpatrol.net/terms/

- The MCP server is for interactive use (questions asked through an AI assistant). No scheduled or automated collection, bulk download or export, dataset building, or supplying data to another product or service
- Automated, bulk, or commercial use requires REST API access under a separate agreement with 60Clicks Media, LLC (contact@watchpatrol.net)
- Rate limits and usage caps apply per account and may change
- No robots, spiders, or scrapers against the website or mobile apps

## Contact

- Website: https://www.watchpatrol.net
- Integrations portal: /integrations/
- Contact form: /contact/