Skip to content
unzoi docs

REST API

Six endpoints. Every one is a GET, every one takes an API key, and every one returns JSON.

Base URL: https://api.unzoi.com. Authentication is one header. Everything below is generated from the OpenAPI document the API serves about itself, so a parameter listed here is a parameter the server accepts.

GET /search Search articles. GET /stories Search, collapsed into deduplicated stories. GET /top-headlines The most recent articles. GET /doc/{id} One article's full metadata. GET /similar/{id} Articles similar to a given one. GET /account This key's plan and usage.

Which one do I want

Three of these search, and the choice between them changes the shape of the answer more than any parameter does.

The questionEndpointWhy
"What happened with X?" /stories One event, returned once, with the outlets that covered it. Forty outlets running the same wire story collapse to one row.
"What has been written about X?" /search Coverage itself is the answer — you want the articles, not the events.
"What is happening right now?" /top-headlines Recency rather than relevance. No query needed; every filter still applies.

The other three follow a thread you already have: /doc/{id} for one article in full, /similar/{id} for what else covered it, and /account for where you stand.

Shared conventions

  • Filters are exact. Every filter field matches an indexed attribute exactly, not fuzzily. Take values from a previous response rather than inventing them — Filters and signals lists all of them.
  • Times are 14 digits. from and to accept 2026-07-09 or 20260709120000; both are normalised to YYYYMMDDHHMMSS UTC, with from padded to the start of the period and to to the end.
  • Paging is offset-based. offset and limit, with has_more in the response — see Pagination and facets.
  • Every response says where you stand. Rate, quota and archive-depth headers ride on all of them; see Limits and plans.
  • Bodies are never returned. The index stores article metadata and derived signals, not full text. url is where the article lives.

Generating a client

The spec is a normal OpenAPI 3.1 document with no vendor extensions, so any generator handles it. See OpenAPI for the commands, or SDKs if you would rather write the forty lines by hand — for six GET endpoints, that is often the smaller thing to maintain.