pricewatcha-api

# Pricewatcha API

The **Pricewatcha API** is the **Structured Product Price Intelligence Platform** for developers, automation and AI Agents.

The Pricewatcha API derives from the [pricewatcha.com](https://pricewatcha.com) application. It provides price tracking, alerts and product intelligence beyond the Pricewatcha dashboard. This repository documents the public HTTP API, OpenAPI schema, official SDKs, MCP server and examples. It does not contain the production web application or scrapers.

**Status:** Available · **Version:** `v1` · **Base URL:** `https://pricewatcha.com/api/v1`

**Interactive API keys (browser):** [Developer page](https://pricewatcha.com/en/developers#api-keys)

---

Optional: verify connectivity with `GET https://pricewatcha.com/api/v1/health`. Then pick one of the three paths below.

### Quickstart

#### Path 1: Browse prices (no auth)

Use demo product IDs from the [demo catalog](https://github.com/pricewatcha/pricewatcha-api/tree/main/public-demo) or search the catalog:

```bash
curl -s "https://pricewatcha.com/api/v1/products/demo_iphone_15_pro"
curl -s "https://pricewatcha.com/api/v1/search?q=iphone+15&limit=10"
```

Search matches product **name**, **URL** and **platform/shop** (case-insensitive). Results include the full Pricewatcha catalog, not only URLs submitted via `POST /track`. Use `product_id` from search for product and price-history endpoints (`prod_*` or `demo_*`).

#### Path 2: Track a product and get price history

```bash
curl -s -X POST "https://pricewatcha.com/api/v1/track" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.backmarket.de/de-de/p/example-product"}'

curl -s "https://pricewatcha.com/api/v1/products/{productId}/price-history"
```

`POST /track` returns HTTP 200 with a bounded server-side long-poll (~25s). Use `product_id` from the response for price history. Optional: send `Authorization: Bearer pwk_live_…` for [higher track quotas](#rate-limits).

Fast shops return `status: "completed"` with the full `product` in one call. Slow shops return `status: "running"` with a `job_id`. Poll `GET https://pricewatcha.com/api/v1/jobs/{jobId}` until the job is `completed` or `failed`. More detail: [Async track & poll](#async-workflow).

#### Path 3: Price alert with webhook (API key required)

Create a key on the [Developer page](https://pricewatcha.com/en/developers#api-keys), then:

```bash
curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4e5",
    "notify_on_drop": true,
    "min_threshold_price": 500.00,
    "webhook_url": "https://your-n8n-instance.com/webhook/abc",
    "notify_email": true
  }'
```

For authentication and data boundaries, see [Authentication](#authentication) and [Data boundaries](#data-model).

---

## Authentication

No credential required for catalog [search](search.md), product detail, price history and [async track/poll](async-workflows.md). Track without a key uses [anonymous rate limits](rate-limits.md). Send an API key on `POST /track` to use the higher per-account track quotas.

Protected API v1 endpoints (alerts, webhooks, authenticated track callbacks) use:

```http
Authorization: Bearer pwk_live_…
```

| Credential | Format | When to use |
|------------|--------|-------------|
| **API key** | `pwk_live_…` | **Recommended** for scripts, agents, n8n and server integrations. Create on the [Developer page](https://pricewatcha.com/en/developers#api-keys). |
| **Login session token** | JWT from `POST https://pricewatcha.com/api/auth/login` | Website UI and [headless key bootstrap](#api-keys-headless-bootstrap) only |

Do not use the login session token for alerts, webhooks or other API v1 calls once you have an API key.

See [Access model](#access-model) for which routes are public vs authenticated.

---

### API keys (browser)

Log in on the [Developer page](https://pricewatcha.com/en/developers#api-keys) to create and manage API keys in your browser. The full secret is shown **once** at creation.

For agents without a browser, use [headless key bootstrap](#api-keys-headless-bootstrap) below.

**Using your key** on protected endpoints:

```bash
curl -s -X POST "https://pricewatcha.com/api/v1/alerts" \
  -H "Authorization: Bearer pwk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_a1b2c3d4e5", "notify_on_drop": true}'
```

---

### Headless key bootstrap (for agents)

If an agent must obtain API credentials without a browser, authenticate once with the same email and password as on the website, create an API key, then use `pwk_live_…` for all further calls. This is not a separate agent login: it is the normal Pricewatcha account login exposed as an HTTP endpoint.

#### How login via API works

`POST https://pricewatcha.com/api/auth/login` accepts JSON `email` and `password` and returns a short-lived `access_token` (login session token). The [Developer page](https://pricewatcha.com/en/developers) login modal calls the same endpoint; in a script or agent you call it directly with `curl` or your HTTP client.

- You need an existing account (register on the site or via `POST https://pricewatcha.com/api/auth/register`).
- The email must be verified: otherwise the API returns **403**.
- Wrong credentials return **401**.
- Use `access_token` only to create keys; for alerts and webhooks use the `pwk_live_…` key from step 2.

**Step 1: Login**

```bash
curl -s -X POST "https://pricewatcha.com/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "YOUR_PASSWORD"}'
```

**Response** (HTTP 200), `AuthResponse`:

- `access_token` (string): login session token (JWT)
- `token_type` (string): always `"bearer"`
- `user` (object): `id` (string, UUID), `email` (string), `email_verified` (boolean)

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "you@example.com",
    "email_verified": true
  }
}
```

Send the token as `Authorization: Bearer <access_token>` in step 2. Session tokens expire; do not store them as the long-term credential for an agent.

**Step 2: Create API key**

```bash
curl -s -X POST "https://pricewatcha.com/api/keys" \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_STEP_1" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent bootstrap"}'
```

**Response** (HTTP 200), `CreateApiKeyResponse`:

- `id` (integer): key ID
- `name` (string): label from the request
- `key_prefix` (string): first 12 characters of the key (for display)
- `key` (string): full secret; returned only on create, not on list
- `is_active` (boolean)
- `created_at` (string, ISO 8601 datetime)
- `last_used_at` (string or `null`)
- `revoked_at` (string or `null`)

```json
{
  "id": 42,
  "name": "agent bootstrap",
  "key_prefix": "pwk_live_ab",
  "key": "pwk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "is_active": true,
  "created_at": "2026-05-27T14:30:00.123456",
  "last_used_at": null,
  "revoked_at": null
}
```

Store `key` securely. Use it on alerts, webhooks and other protected API v1 endpoints, not the session token from step 1.

---

### API endpoints (overview)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `GET` | `/api/v1/health` | - | Health check |
| `GET` | `/api/v1` | - | Discovery and disclaimer |
| `POST` | `/api/v1/track` | - | URL ingestion (long-poll) |
| `GET` | `/api/v1/jobs/{jobId}` | - | Job status |
| `GET` | `/api/v1/products/{productId}` | - | Product intelligence |
| `GET` | `/api/v1/products/{productId}/price-history` | - | History and trend |
| `GET` | `/api/v1/search?q=` | - | Keyword search (`limit` max 200) |
| `GET` | `/api/v1/openapi.json` | - | Live OpenAPI 3.1 |
| `POST` | `/api/auth/login` | - | Login (short-lived session token) |
| `POST` | `/api/keys` | Session token | Create API key |
| `GET` / `DELETE` | `/api/keys` … | Session token or key | List / revoke keys |
| `*` | `/api/v1/alerts` … | API key | Price alerts |
| `*` | `/api/v1/webhooks` … | API key | Webhook subscriptions |

Machine-readable contract: [openapi/openapi.yaml](openapi/openapi.yaml) · Live: `GET https://pricewatcha.com/api/v1/openapi.json`

---

## Rate limits

### Current limits (indicative)

The following limits apply and may change without notice.

| Class | Endpoint | Anonymous | Authenticated (API key) |
|--------|----------|-----------|-------------------------|
| Track (concurrent) | `POST /track` | ~2 in-flight jobs | ~4 in-flight jobs |
| Track (burst) | `POST /track` | ~10 jobs / 60s | ~20 jobs / 60s |
| Track (hourly) | `POST /track` | ~40 jobs / hour | ~120 jobs / hour |
| Track (daily) | `POST /track` | ~80 jobs / day | ~400 jobs / day |
| Job poll | `GET /jobs/{id}` | ~40 req/min per client | same |
| Read | `/search`, `/products`, `/price-history` | ~60–120 req/min per client | same |
| Health | `/health` and `/` | Unlimited | Unlimited |

Send `Authorization: Bearer pwk_live_…` on `POST /track` to use the authenticated tier. Track remains available without a key at the anonymous limits.

> **Client identity:** anonymous limits are keyed by client IP. Behind Cloudflare the API prefers `CF-Connecting-IP` over `X-Forwarded-For` so edge proxy IPs are not treated as distinct clients. The hosted MCP server forwards a stable `X-Pricewatcha-Client-Id` (OAuth token hash, else connecting-IP hash) with a shared proxy secret so MCP callers are not all bucketed under one egress IP. Authenticated track quotas are keyed by account (`owner_id`), not IP.

> Monitor `X-RateLimit-Remaining` and honor `429` with exponential backoff. `X-RateLimit-Policy` names which window the headers refer to (`track`, `track_hourly`, `track_daily`, `track_concurrent`, `job_read`, or `read`).

**Track quotas are counted from persisted jobs** (`api_track_jobs` by client key or accoun