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). |
get_story | /stories/{id} | Expand one story by its story_id (from list_stories or any article): the article and outlet counts, every outlet, when it was first and last seen, the entities and topics it is about, and its newest articles as compact hits. |
resolve_entity | /entities | Find the spellings the index holds for an organization, person, place, topic, author or source, before filtering on it. |
aggregate_news | /aggregate | A time series over the match set: per calendar bucket (hour, day, week, month, or `all` for one bucket), the article count and optionally the distinct story count, the distinct outlet count and a signal's mean and percentiles. |
related_entities | /graph/related | The entities most often mentioned alongside one entity (organizations, people, places, topics), strongest first, each with its co-mention count and share and, for the strongest, the newest articles mentioning both plus distinct sources, stories and first and last seen. |
connection_path | /graph/path | How two entities connect in the reporting: the articles mentioning both, and up to five paths through one shared neighbour, each hop with its co-mentions and evidence. |
entity_network | /graph/network | One entity's neighbours grouped by type for a window. |
shared_exposures | /graph/exposures | What up to five entities have in common: the articles mentioning all of them, their distinct stories and sources, the facets you ask for (topics, countries, sources and so on), mean and percentile intensities of the signals you name, and the newest shared articles as evidence. |
create_watch | POST /watches | Save a /stories query the index runs for you every interval_minutes, instead of polling. |
list_watches | /watches | List this account's watches with their status (active, paused_key, paused_credits, failing), last and next run, and the plan's cap. |
get_watch | /watches/{id} | Read one watch: the /stories query it runs, its interval and minimum_outlets, which events it records, its webhook_url, and its status (active, paused_key, paused_credits, failing) with the last and next run and the watermark. |
delete_watch | DELETE /watches/{id} | Delete a watch with its state and its events. |
watch_events | /watches/{id}/events | Read a watch's events, newest first: new_story and story_growth, each with the story's counts and, when a webhook is set, its delivery status. |
account_status | /account | Report this session's account: plan, credits a minute, the monthly credit allocation and how much of it is used, whether the key stops at its allocation or bills overage, how far back the plan may query (history_days; null = the full archive), calls and credits 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.