Unzoi documentation
Unzoi is a search API over a global news index. Articles from outlets worldwide, ranked by keyword, by meaning, or by both — and collapsed into stories, so one real event comes back once with the outlets that covered it rather than forty times.
There are two ways in, and they are the same API. A REST API for code you write, and an MCP server for an agent that decides for itself what to look up. Both authenticate with the same key, bill against the same allowance, and return the same JSON — the MCP tools are generated from the REST contract, so they cannot answer a question differently.
The two surfaces
Reach for REST when you know what to search for: a scheduled job, a dashboard, a pipeline, anything where the query is written in your code. Reach for MCP when a model is deciding, because the tool descriptions are written for one to read and it will pick between article search and story clustering on its own.
| Tool | REST equivalent | What it does |
|---|---|---|
search_news | /search | Search the news index. |
list_stories | /stories | Search and collapse results into deduplicated stories (one real event across many outlets). |
top_headlines | /top-headlines | Most-recent articles, optionally filtered by indexed article metadata and time range. |
get_article | /doc/{id} | Fetch a single article's rich metadata by id, including names, structured locations and dates, quotations, amounts, related media, links, and alternate URLs. |
find_related | /similar/{id} | Find articles semantically similar to a given article id (More-Like-This). |
account_status | /account | Report this session's account: plan, per-minute rate limit, monthly quota and how much of it is used, whether the key stops at its quota or bills overage, how far back the plan may query (history_days; null = the full archive), calls made this session, and whether metered billing is active. |
The one thing worth knowing first
News is repetitive. A single wire story runs, verbatim or near enough, across dozens of outlets, and a plain search
returns all of them. /stories — and the
list_stories tool — collapse that into one row per event, with an
article count and an outlet count attached.
If results are going into a model's context window, that is the single biggest saving available here, and the counts tell you how big a story is, which plain search throws away. The guide explains when it is and is not the right call.
Machine-readable
Every reference page on this site is generated from documents the API serves about itself, so they cannot describe an API the server does not implement. You can read them directly, with no key:
https://api.unzoi.com/openapi.json— OpenAPI 3.1https://api.unzoi.com/mcp/tools.json— the MCP tool schemashttps://api.unzoi.com/llms.txt— the whole API in one plain-text pagehttps://api.unzoi.com/mcp— the MCP endpoint itself
Keys are issued at console.unzoi.com. The free tier needs no card.