# 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.

Paid price intelligence lives under /api/x402/pricing/: the catalog endpoint is free (trusted component list, live per-query price, payment rails, and data contract), and the component query costs ~$0.01 over HTTP 402. We support dual-rail machine payments: x402 (Coinbase CDP/Base) and MPP (Machine Payments Protocol by Tempo/Stripe via USDC). The 402 response is authoritative for payment parameters; no account or API key is needed on the paid path. Guides: https://hardwarehunter.io/docs/paying-with-x402 and https://hardwarehunter.io/docs/paying-with-mpp

## Rate Limits

- Effective app limit: 30 requests/minute/IP
- Paid price intelligence (x402 & MPP): GET /api/x402/pricing/catalog is free (trusted components, strata, rails, live price); trusted data from GET /api/x402/pricing/component/{id} costs ~$0.01/query and returns 402 with dual-rail payment instructions (x402 + MPP); insufficient components are free

## 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`

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

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

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

Evaluate a listing: component-match diagnostics plus direct listing
facts. Market benchmarks are quarantined (2026-08-14), so the verdict is
``INCONCLUSIVE`` and all benchmark-derived fields are null until a trusted
comparable-listing cohort exists.

## 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 cached (≤60s) subscription status.

### 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.