NewsGraph documentation
NewsGraph watches 150,000 publishers and answers one question on a schedule: has this topic moved since I last looked? This is how to call it, and how to pay for it.
The shape of an integration
An agent picks a topic, keeps a cursor, and asks whether anything changed. It never reads a feed, and it never re-reads what it has already seen.
- Pick a beat. A beat is a saved topic with its own article cluster.
- Poll it. You get back
moved:false, or a small pack of new articles. - Keep the cursor. It is opaque, signed and beat-bound. Store it; it is how you avoid repeats.
- Cite the link. Items never contain article bodies — a headline, a link that resolves to the story, and the publisher's name.
Access
There is no key to obtain and nothing to sign up for. Every route is read-only and public, so you can build against it immediately. Anonymous callers get 120 requests a minute; an optional key raises that to 1200.
| Route | Returns |
|---|---|
GET /v2/topics | The catalog: stable IDs, labels, and whether a topic currently has articles |
GET /v2/news?beat_id= | Articles for a topic, plus a cursor to check from later |
GET /v2/changes?beat_id=&cursor= | Only what appeared since that cursor — usually nothing |
GET /v2/brief?beat_id= | The top three headlines verbatim, each with its source and UTC time — a sentence’s worth of news, not a summary |
GET /v2/tools | The same capabilities in OpenAI function-call shape |
POST /mcp | The same tools over MCP, for agent frameworks |
No article bodies exist at any price. An item carries a headline, a link that resolves to the article, the publisher’s name and the time it was published — the story stays with them.