Home · Docs · Endpoints · archive/coverage
archive/coverage — which niches exist, and how deep each goes
The free, keyless endpoint that every other archive call should start from. Served at /api/v1/nichos.
This is archive data, and that is the point. A live platform API can tell you what is happening now. It cannot tell you what was happening last Tuesday, because it does not keep a record. We wrote down every hour, which is why this endpoint can answer a question about the past at all.
The call
| Path | GET /api/v1/nichos |
|---|---|
| Catalogue id | archive/coverage |
| Cost | 0 credits per call. A call that finds nothing is charged all the same. |
| Key | Not required. No key, no credits. |
Parameters (0)
None. This endpoint takes no inputs at all — it describes what the archive holds, and there is nothing to narrow.
What the parameter list does not tell you
NO KEY AND NO CREDITS, and the id in the catalogue is `archive/coverage` — there is no `archive/nichos` row. Discovery is not product: this endpoint tells you the archive exists and since when, and never hands over a single archived row.
IT IS ALSO THE CHEAPEST BUG PREVENTION IN THIS API. Nothing downstream validates a niche name. A typo against `/trends` or `/movers` does not 404 — it returns an empty list, HTTP 200, and spends the call anyway, because the quota counter increments before the archive is read. So an empty answer means either 'this niche was quiet' or 'this niche does not exist', and the response cannot tell you which. One free call here removes the ambiguity entirely, which is why step 1 of all three recipes is this endpoint.
`windows_24h` is how many hourly windows landed in the last day, and `last_window` is the most recent one. Together they are a coverage statement, not a health check: a niche with 24 windows has complete recent history, and one with 9 has gaps you should know about before you read a flat series as a quiet market. The live state of each source is on the status page, which is dynamic for exactly that reason.
`last_window` can be null, and null means no window has been recorded for that niche — not that the last one was at epoch. The distinction matters when you are deciding whether a niche is new or broken.
Measured caveats (1)
A nonexistent niche is not a 404 — and it spends the call
Nothing validates the niche name. A typo returns `items: []` with `points: 0` and HTTP 200, AND still spends a call, because the quota counter increments before the archive is read. An empty answer therefore means one of two different things — the niche is quiet, or the niche does not exist — and the response does not distinguish them. This is why step 1 of every recipe here resolves names at `/api/v1/nichos` first: that endpoint is free and needs no key, so the check costs nothing.
Source: The `/api/v1/trends/{niche}` description in the served `/openapi.json`.
Real responses
Captured, not composed. 1 response we could actually make from this machine:
$ curl -s "https://honesthook.com/api/v1/nichos"
{"niches":[{"id":"ai-agents","label":"AI agents","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"},{"id":"devtools","label":"Developer tools","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"},{"id":"indie-saas","label":"Indie SaaS","windows_24h":24,"last_window":"2026-10-02T09:00:00+00:00"}]}Response shapes (1)
ApiError— Every 4xx and 5xx from the API carries this object. The `error` value is a stable string you can branch on; the extra fields appear only for the errors that have something to report.
Error codes (1)
Every one of them carries the same body shape: ApiError. The error value is a stable string you can branch on — branch on that, never on the message text.
503
Machine-readable
This endpoint is in /openapi.json (OpenAPI 3.1), with its cost on the operation itself. If you are generating a client, use the spec rather than this page — and note that the spec is filtered by what is switched on right now, so it is the better answer to "can I call this today".
The other 6 endpoint pages
archive/trends · archive/movers · profile/history · youtube/channel · pinterest/boards · bluesky/post