# Hardware Hunter API

> Full API reference for AI agents. Price intelligence for PC hardware components.

## Authentication

Authenticated endpoints use an API key as a Bearer token:

    Authorization: Bearer <api_key>

Your human provisions this key: they receive it at registration and can view or regenerate it anytime under API access in their account settings (https://hardwarehunter.io/account). Regenerating immediately invalidates the old key.

Public endpoints (under /api/public/ and /.well-known/) are public, read-only, and need no authentication.

## Rate Limits

- Free: 60 requests/min
- Pro: 300 requests/min
- Lifetime: 10,000 requests/min

## Public read-only endpoints

- `GET /api/public/prices` — hardware categories with component counts
- `GET /api/public/prices/{category}` — components + market summaries (p25/median/p75)
- `GET /api/public/prices/{category}/{component_id}` — specs, stats, observations
- `GET /api/public/deals` — current scored listings (ALERT/WATCH), filterable
- `GET /.well-known/webmcp` — WebMCP tool catalog
- `GET /tools.json` — machine-readable tool schema

## Endpoints

## Hunts

### GET /hunts
_List all hunts for the current user_
- **Auth:** Requires: Bearer API key
- **Params:** `limit`, `offset`

### POST /hunts
_Create a new hunt_
- **Auth:** Requires: Bearer API key

### GET /hunts/results
_Paginated results feed across all hunts for the current user_
- **Auth:** Requires: Bearer API key
- **Params:** `filter`, `limit`, `offset`, `hunt_id`

Returns all scan results across all of the user's hunts, newest first.
Each row joins hunt_scan_results → listings → hunts, with alert_channel from alerts.

filter:
  all       — everything
  alerted   — action=ALERT
  near_miss — action=WATCH
  skipped   — action=SKIP

### DELETE /hunts/{hunt_id}
_Delete a hunt (hard delete)_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`

### GET /hunts/{hunt_id}
_Get a specific hunt_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`

### PATCH /hunts/{hunt_id}
_Update a hunt_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`

### GET /hunts/{hunt_id}/alerts
_List recent alerts fired for a hunt_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`, `limit`, `offset`

### GET /hunts/{hunt_id}/listings
_List listings evaluated for a hunt (recent alerts)_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`, `limit`, `offset`, `action`

Returns listings that were evaluated for this hunt.
Filter by action=ALERT|WATCH|SKIP or leave blank for all.

### POST /hunts/{hunt_id}/scan
_Trigger a manual scan for this hunt_
- **Auth:** Requires: Bearer API key
- **Params:** `hunt_id`

## Components & evaluation

### GET /api/v2/components/search
_Search Components_
- **Auth:** Requires: Bearer API key
- **Params:** `q`, `category`, `limit`, `cursor`, `local_kw`

### GET /api/v2/components/{component_id}
_Get Component_
- **Auth:** Requires: Bearer API key
- **Params:** `component_id`, `local_kw`

### GET /api/v2/components/{component_id}/history
_Get Price History_
- **Auth:** Requires: Bearer API key
- **Params:** `component_id`, `period`, `local_kw`

### POST /api/v2/evaluate
_Evaluate_
- **Auth:** Requires: Bearer API key

Evaluate a listing price against historical market data.

This is the main entry point for the "killer feature" — given a URL,
title, and price, it matches the component, pulls historical pricing,
and returns a BUY / WAIT / SKIP / INCONCLUSIVE verdict.

## Notification channels

### GET /users/me/channels
_List Channels_
- **Auth:** Requires: Bearer API key

### POST /users/me/channels
_Create Channel_
- **Auth:** Requires: Bearer API key

### DELETE /users/me/channels/{channel_id}
_Delete Channel_
- **Auth:** Requires: Bearer API key
- **Params:** `channel_id`

### PATCH /users/me/channels/{channel_id}
_Update Channel_
- **Auth:** Requires: Bearer API key
- **Params:** `channel_id`

### POST /users/me/channels/{channel_id}/test
_Test Channel_
- **Auth:** Requires: Bearer API key
- **Params:** `channel_id`

## Account & billing

### GET /account/me
_Get account details_
- **Auth:** Requires: Bearer API key

### GET /billing/status
_Current billing tier and subscription info_
- **Auth:** Requires: Bearer API key

Returns tier, Stripe IDs, and live subscription status from Stripe.

### GET /users/me/entitlements
_Get effective tier entitlements for the current user_
- **Auth:** Requires: Bearer API key

Effective cadence/cap contract for the authenticated user.

The dashboard uses this instead of reconstructing tier rules in
JavaScript. active_hunt_count includes hunts with a future paused_until
(a timed pause does not free the slot); remaining is clamped at zero so
grandfathered/over-cap data cannot produce a negative UI value.