Public API · read-only
Harpd public API
Harpd exposes its product discovery data through public, read-only endpoints. There is no API key, no signup and no rate-limit contract — every endpoint is cached at the edge and served under CC BY 4.0. This page documents only what is public; private surfaces (auth, billing, credits, admin) are not part of this API and are never exposed here.
Quick answer
Is the Harpd API public and free to use?
Yes. All documented endpoints are public read-only APIs — no authentication, no API key, no signup. Responses are edge-cached (Cache-Control: public, max-age=3600 for datasets) and the data is licensed CC BY 4.0: free to reuse commercially with attribution to Harpd.
- Auth
- None required
- License
- CC BY 4.0
- Schema
- v1.0
- Methodology
- harpd.com/rank/methodology/
Data source: Harpd public APIDataset indexMethodologyCitations
Datasets (harpd.com/data)
Every endpoint shares one envelope: schemaVersion, generatedAt,lastUpdated, source, methodology, licenseand count. Field definitions for every record live at/data/schema.json.
| Method | Path | Description |
|---|---|---|
| GET | /data/rank.json | Overall ranking: one record per approved product with rank, Rank Points, category and verification status. |
| GET | /data/rank.csv | The same ranking dataset as a flat CSV. |
| GET | /data/top-products.json | Top 100 with movement, maker website and alternatives URL. |
| GET | /data/market-index.json | Category aggregates: product count, Rank Points, share and leader. |
| GET | /data/products.json | Ranking fields plus each product’s public website, description and product type. |
| GET | /data/categories.json | Every category board with description, state and product count. |
| GET | /data/rank-history.json | Closed monthly and weekly period snapshots. |
| GET | /data/answers.json | Every published /answers/ page: question, intent, live board and summary. |
| GET | /data/comparisons.json | Every indexable comparison with both subjects and their ranks. |
| GET | /data/alternatives.json | Every indexable alternatives page with its peer list in board order. |
| GET | /data/research.json | Every published monthly research report. |
| GET | /data/evidence.json | The claim/evidence register as a typed graph. |
| GET | /data/llm-pricing.json | Model pricing per 1M tokens, verified against official provider pages. |
| GET | /data/llm-pricing.csv | The pricing dataset as CSV. |
| GET | /data/benchmarks.json | Benchmark records in long format with an explicit isModeled flag. |
| GET | /data/benchmarks.csv | The benchmark dataset as CSV. |
| GET | /data/methodology.json | The exact rules behind the ranking numbers, as data. |
| GET | /data/rank-open-data.json | Objective signals only: verified GitHub stars and first-party referral counts. |
| GET | /data/schema.json | The field dictionary for every endpoint and what is excluded. |
Rank API (api.harpd.com)
The live board family, served by the Harpd collector. Responses only ever contain approved, active public listings.
| Method | Path | Description |
|---|---|---|
| GET | /api/rank | Live overall board (scope=overall|monthly|weekly, category=all|{slug}). |
| GET | /api/rank/archives | Closed monthly and weekly periods with product counts. |
| GET | /api/rank/archive/:type/:key | Immutable snapshot of a closed period (type=monthly|weekly). |
| GET | /api/rank/product/:slug | Product profile: listing, per-board ranks, history and related products. |
| GET | /api/rank/new | Most recently approved listings. |
| GET | /api/rank/trending | Organic 7-day trending (independent of Rank Points). |
| GET | /api/public/rank/stats | Board-level public statistics. |
| GET | /api/v1/rank/open-data.json | Open-data projection of the rank dataset. |
| GET | /api/agent/v1/rankings | Ranking feed for agent consumers. |
| GET | /api/agent/v1/products/:slug | Product record for agent consumers. |
| GET | /openapi.json | The machine-readable API contract. |
| GET | /.well-known/agent.json | Agent capability discovery manifest. |
SEO/GEO payload (harpd.com/api/seo)
The machine-readable twin of the marketing site: what a page says, which entities and claims it carries, and where the evidence lives. Used by answer engines and crawlers;/api/seo/ is the only path under /api/ allowed by robots.txt.
| Method | Path | Description |
|---|---|---|
| GET | /api/seo/page/{path} | Machine-readable per-page payload: title, summary, entities, claims, evidence, updatedAt, canonical, methodology. |
| GET | /api/seo/pages.json | The full generated page inventory (precomputed static asset). |
| GET | /api/seo/dashboard.json | Health score, inventory summary, authority graph and pipeline state. |
Authentication, rate limits & caching
Authentication. None of the documented endpoints require a key or session. They are public read-only surfaces; write paths and private data live behind the app authentication system and are intentionally not documented here.
Rate limits. There is no published per-key limit because there is no key. Datasets are serialized from the same edge-cached Rank feed the site uses and served with Cache-Control: public, max-age=3600; the SEO/GEO payload endpoints cache at 60s with 300s edge revalidation. Re-fetching the same URL reuses the cached response.
Freshness. Every dataset carries its own lastUpdated — the most recent record-level change, never a rebuild date. Poll for that field instead of re-crawling blindly.
Robots. /api/ is disallowed for crawlers except /api/seo/. Human and agent consumers may fetch any documented endpoint directly.
Examples
# Top 10 products on the overall board
curl -s https://api.harpd.com/api/rank?scope=overall\&category=all | head -c 400
# The full dataset, as JSON
curl -s https://harpd.com/data/rank.json
# A product's machine-readable SEO/GEO payload
curl -s https://harpd.com/api/seo/page/rank/
# Published research periods
curl -s https://harpd.com/data/research.jsonAttribution & licensing
All public data is licensed CC BY 4.0: you may quote, redistribute and build on it — including commercially — as long as you attribute Harpd and link the licence. Copy a ready-to-cite line from thecitation hub. The methodology behind every number is published at/rank/methodology/ and mirrored at/data/methodology.json. Rank Points are promotional placement, not an editorial quality score — describe them that way when you reuse the data.
What is public, what is excluded and how the datasets are produced is stated on thedataset index and the evidence register.