Home / How it works

Sources, adapters, the Event Graph, surfaces

How it works

The index is built in four layers: the sources it reads, the adapters that turn each one into the same kind of record, the graph those records build, and the two surfaces you query. Every part below carries a status, and nothing here describes a capability before it exists.

The sources

Today the hosted index is built from one adapter: a public feed of article metadata. A second, for publisher RSS and Atom feeds, is being built, and every article already records which adapter it arrived through.

The list below is what the ingestion layer is designed for, not what is running. A row marked planned is a shape the seam already fits, and nothing more than that. Adding a source is a configuration change rather than a rebuild, which is the property that matters if you intend to choose your own.

Source kindWhat it givesStatus
GDELT, an aggregate metadata feed A public feed of article metadata, topics and entities. The source the index was first built from, and today the only one that supplies enrichment. Live
Publisher and broadcaster feeds RSS and Atom, fetched directly from the publisher. Title, link, outlet, publication time, summary. Being built
Licensed wires A wire service under the customer’s own licence, ingested the same way. Planned
Government and institutional feeds Official releases and publication feeds, as a source alongside reporting about them. Planned
Discovery crawling Finding articles from sitemaps and section pages rather than waiting for a feed to mention them. Planned
Broadcast transcripts Spoken coverage as text, so what was said on air is searchable beside what was written. Planned
Social sources Public posts as a signal about what is being said, clearly separated from reporting. Planned

The adapters

An adapter turns one kind of source into the same article record: title, link, outlet, language, publication time, and whatever that source supplies beyond them. Everything downstream — clustering, the graph, search — reads records, not formats, so a new kind of source does not change how anything else behaves.

What a source does not carry is left absent rather than empty. A feed that supplies no topics produces an article with no topics, which the API reports as unavailable rather than as an article about nothing. The difference matters when a model is reading the answer: empty reads as "we looked and found none".

What is read, and what is returned

These are two different things, and the difference is the product. The analysis covers the whole article: topics, organisations, people, places, amounts, quotes, tone and the signal scores all come from the full text, which is why each article carries its own word count and why the signals are measured per hundred words of it. Story clustering reads that same material, which is how it catches two outlets covering one event in different words.

What a response returns is the headline, the publisher, the timestamp, the link, the story, and everything derived from that reading. It does not return the article text. That is a deliberate boundary, not a gap: the text belongs to the publisher who wrote it, and an index that redistributed it would be selling something it does not own. If your application needs the words themselves, license them from the publisher.

Provenance

Every article names the adapter and the feed it came through, both of which you can filter and count on. Every response carries the attribution its sources require, composed from the adapters that answer actually contains rather than fixed in advance. Article bodies are never redistributed: results link to the publisher.

A model that cannot say which source an item came from cannot be audited, which is the whole reason these are fields on the record rather than a line in a contract.

Grading publishers

A story listing forty outlets tells you how widely something travelled. It does not tell you how many newsrooms actually reported it, because one wire report reaches many outlets and the list looks identical either way. A publisher profile is how those are told apart: for each story an outlet touched, was it the first to report, or was it carrying someone else's work, and by how long.

Everything in a profile is measured from that outlet's own articles, which you can go and read. Nothing in it is an assessment of accuracy, credibility or editorial quality, and no such score is offered. A newsroom that is usually first is usually first; whether it is right is a different question and not one an index can answer. Every response says so, and says what sample the rates were computed over.

The Event Graph

What the records build, and what the API serves. The clustering, entity resolution and relationship layers are ours and run on articles from any source; the enrichment layers that fill in entities and topics are, today, supplied by one source rather than computed by us.

Sources

  • Aggregate metadata feed
  • Publisher and broadcaster feeds
  • Licensed wires
  • Government and institutional feeds

+3 more kinds planned

The Event Graph

  • Stories
  • Entities
  • Relationships
  • Signals
  • Watches
  • Provenance
  • Publisher profiles

Read from the whole article · 4 more parts planned

Surfaces

  • REST API
  • MCP server, 18 tools

Same filters, same key, same credits

Your stack

  • Agents and assistants
  • Backends and pipelines
  • Feeds inside a product

Where it runs

  • Unzoi Cloud
  • Your cloud
  • Private network
  • Disconnected
The four layers on one line. Each part is marked live, being built or planned, from the same roadmap as the tables on this page.
PartWhat it isStatus
Stories One event returns once, carrying every outlet that covered it. Clustering is ours, and it runs on articles from any source. Live
Entities A name resolves to the spellings the index holds, grouped under one id you can filter on. Live
Relationships Who is reported alongside whom, how two entities connect, and what a watchlist shares. Every answer carries its evidence articles. Live
Signals Scored language dimensions per article, filterable by numeric range. Live
Watches A story query the index runs on your interval, with an event feed and signed webhooks. Live
Provenance Every article names the adapter and feed it came through. Every response carries the attribution its sources require. Being built
Native enrichment Entities, places, dates, amounts and signals computed by us from the article text, so a record from any source carries the same fields. Planned
Publisher profiles Whether an outlet breaks stories or carries them, how far behind it runs when it is not first, what it covers and in which languages — measured from its own publishing, not asserted. Being built
Cross-lingual event identity One event, one story, across languages — so regional and national coverage of the same thing arrive together. Planned
Event timelines First report, and how coverage spread between sources over time. Planned
Change detection Watches that fire on a first report or a jump between countries, not only on a count that moved. Planned

The surfaces

One implementation behind two surfaces: a REST API for your backend, and a first-party MCP server for agents. Both take the same filters and return the same fields, so behaviour does not diverge between the path your code takes and the path an agent takes. Every operation and field is in the reference, and where each article came from is in data and sources.

Where it runs

Today, on our infrastructure. The other modes below are planned rather than available, and the sovereign page says what would have to be true for each of them.

ModeWhat it meansStatus
Unzoi Cloud The hosted API and MCP server. What every plan on the pricing page runs on. Live
Your cloud The same build in an account you own, reading and writing storage you control. Planned
Private network No public endpoint: the API reachable only from inside your network. Planned
Disconnected Ingest from sources inside your perimeter, with no egress at all. Planned

What the statuses mean

WordMeans
Live In production, on the public API, documented.
Being built Merged or in progress, not yet true of the hosted index.
Planned Designed far enough to state what would have to be measured. Not started.

Mirrored from the engineering roadmap on 2026-09-20. One place decides these words; this page renders them.

Does it score how reliable a source is?

No. There is no reliability, credibility or trust score anywhere in the product, and a story’s outlet list is breadth of distribution before it is evidence of corroboration: one wire report reaches many outlets. What does exist is a publisher profile: whether an outlet breaks stories or carries them, and how far behind it runs when it does not, measured from its own publishing. That is a statement about behaviour, not about whether the reporting is right.