API Reference

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 [email protected].
• 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.