Connecting

One endpoint, four calls, and no credential. This page is the reference for getting pointed at it — the quickstart is the tour, and this is what you come back to.

The endpoint

base

https://newsgraph.vercel.app/api

Everything is a GET. There is nothing to install, no SDK to keep in step, and no key to obtain before your first request — an anonymous caller can read the whole public surface, at 120 requests a minute.

MCP

If your assistant speaks MCP, this is the shortest path. Add one server and it gains four tools; you do not write a client at all.

your MCP client’s config

{
  "mcpServers": {
    "newsgraph": {
      "url": "https://newsgraph.vercel.app/api/mcp"
    }
  }
}

The four tools it gains:

Tool	Use it to
`newsgraph_topics`	Find a topic. Never invent a `beat_id` — search, then use what comes back
`newsgraph_news`	Read a topic and take a baseline cursor
`newsgraph_changes`	Ask what is new since that cursor
`newsgraph_brief`	Get the top three headlines with no synthesis

HTTP

Anything that can make a request can use this. Four routes, no ordering requirement.

the whole loop

# 1. find the topic
curl -s "https://newsgraph.vercel.app/api/v2/topics?q=nvidia"

# 2. read it, and keep the cursor from the response
curl -s "https://newsgraph.vercel.app/api/v2/news?beat_id=b_bb964843350e"

# 3. later: only what appeared since that cursor
curl -s "https://newsgraph.vercel.app/api/v2/changes?beat_id=b_bb964843350e&cursor=<cursor>"

# or skip to headlines
curl -s "https://newsgraph.vercel.app/api/v2/brief?beat_id=b_bb964843350e"

The cursor is the whole product. Send it back and the answer is either nothing — which is a successful answer, and the cheap one — or the handful of stories that appeared since.

Tool calling

If you would rather hand a model schemas than a URL, they are served rather than vendored, so they cannot drift from the API:

GET /v2/tools

curl -s "https://newsgraph.vercel.app/api/v2/tools"

The response is OpenAI function-call shape. Supply it to your model, execute what comes back, send the results into the next turn.

Keys and rate limits

A key is optional and does not unlock anything. It raises your ceiling. The API is read-only and public, and stays that way.

Caller	Limit	Identified by
Anonymous	120 requests / minute	Calling address, hashed and never stored
With a key	1200 requests / minute	`Authorization: Bearer ng_…`

Keys are issued by hand while the catalog is still settling — there is no self-serve form yet. Ask, and you get a ng_-prefixed secret shown once. Only its hash is stored, so a lost key cannot be recovered; you are issued another.

Every response carries the current state:

response headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 43          # seconds until the window rolls over
X-RateLimit-Tier: anonymous

When something goes wrong

Status	Meaning	What to do
`200`, empty `items`	Not an error	Report nothing new. Do not retry
`400`	The cursor is malformed or expired	Re-baseline with `/v2/news` and take the new cursor
`404`	Unknown `beat_id`	Re-read `/v2/topics`. Never guess an id
`429`	Rate limited	Wait for `Retry-After`. A key raises the ceiling
`503`	Storage unreachable	Back off. Never retry a 4xx in a tight loop

A cursor is signed and bound to one topic. It cannot be reused for another, and an old one will not return a wider window — it will return the same one, and you will have paid for nothing.

Check it works

two commands

# liveness
curl -s "https://newsgraph.vercel.app/api/health"

# a real answer, from a topic that has one
curl -s "https://newsgraph.vercel.app/api/v2/brief?beat_id=b_bb964843350e"

A brief with headlines means you are connected. A brief reading NVIDIA — nothing moved. also means you are connected — it means the topic is quiet.

← Quickstart Topics and articles →