> For the complete documentation index, see [llms.txt](/llms.txt).

Hardware Hunter exposes a JSON API for agents and automation. This page documents every endpoint in the curated public spec, which is also served machine-readable at `/api/public/openapi.json`.

## Base URL

```
https://hardwarehunter.io
```

## Authentication

Authenticated endpoints use an API key sent as a Bearer token:

```
Authorization: Bearer <api_key>
```

- Your API key is shown **once at registration**. There is no self-service way to regenerate a lost key yet — keep it safe, or email `hello@hardwarehunter.io`.
- Endpoints marked **Public** need no auth. Endpoints marked **Requires: Bearer API key** are scoped to your account and respect your tier.

## Rate limits

Rate limits are per account tier, rolling per minute:

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

The public read-only endpoints (below) additionally follow the x402 protocol: the first 50 requests/day/IP are free, then HTTP 402 with payment instructions.

## Public read-only endpoints

These are served outside the OpenAPI schema (they're `include_in_schema=False`), but they're stable and agent-friendly:

- `GET /api/public/prices` — hardware component categories with 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

## The endpoints

Below is the full curated spec, rendered live from `/api/public/openapi.json` — it cannot go stale.


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