API Reference

Hardware Hunter exposes a JSON API for agents and automation. This page documents every endpoint in the curated public spec, which is served machine-readable at /openapi.json (and /api/public/openapi.json), with authentication policies documented at /auth.md.

Base URL

https://hardwarehunter.io

Authentication

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

Authorization: Bearer <api_key>

• You receive your API key at registration, and you can view or regenerate it anytime under API access in your account settings. Regenerating a key immediately invalidates the old one.
• Endpoints marked Public need no auth. Endpoints marked Requires: Bearer API key are scoped to your account and respect your tier.

Rate limits

The effective application limit is 30 requests/minute/IP.

Paid price-intelligence endpoints support dual-rail machine payments over x402 and MPP: trusted benchmarks return HTTP 402 with self-describing payment instructions (~$0.01/query; inspect the live response for network and asset). The catalog and insufficient components are free.

Paid price intelligence (x402 & MPP)

Per-query payment for trusted price data — no API key on the paid path. Supports both x402 (Coinbase CDP/Base) and MPP (Machine Payments Protocol by Tempo/Stripe via USDC).

• GET /api/x402/pricing/catalog — free: trusted components (each with name + capacity), strata, payment rails (x402, mpp_tempo), live per-query price, the data contract
• GET /api/x402/pricing/component/{component_id} — the paid query (~$0.01): cohort median/p25/p75, window, sample size, benchmark_trust metadata, capacity, and condition-stratified rows where published. Benchmarks are per exact SKU (model + capacity)

Payment flow: a trusted benchmark returns 402 with dual-rail challenges:

• x402: PAYMENT-REQUIRED header (Base64 JSON: scheme, network, asset, amount, pay-to); retry with PAYMENT-SIGNATURE carrying signed EIP-3009 transfer; server settles via facilitator and returns 200 with PAYMENT-RESPONSE receipt.
• MPP: WWW-Authenticate: Payment ... challenge header and RFC 9457 problem details; retry with Authorization: Payment ... header; server settles on Tempo and returns 200 with Payment-Receipt receipt.

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

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.