Quickstart

1. Pick a topic

A topic is a saved subject with a stable ID. The catalog lists every one, and says which currently have articles — seventeen of the twenty do not yet.

curl /api/v2/topics

{
  "topics": [
    {
      "beat_id": "b_bb964843350e",
      "label": "NVIDIA",
      "status": "stale",
      "last_success_at": "2026-09-13T09:02:11Z",
      "last_checked_at": "2026-09-13T09:02:11Z"
    }
  ]
}

Keep the beat_id. It is stable, and it is the only argument the other routes need.

2. Read the baseline

Fetch the current articles for your topic and keep the cursor from the response. That cursor is your position — it is signed and bound to this topic.

{
  "items": [
    {
      "id": "930",
      "beat_id": "b_bb964843350e",
      "title": "Blackwell vs Rubin: NVIDIA's AI GPU Battle Moves Into the Agentic AI Era",
      "url": "https://infotechlead.com/?p=98306",
      "source": "InfotechLead",
      "published_at": "2026-09-13T08:46:24+00:00",
      "first_indexed_at": "2026-09-13T08:49:43.062446+00:00"
    }
  ],
  "estimated_tokens": 1840,
  "has_more": false,
  "cursor": "c_eyJiIjoi…",
  "freshness": "stale"
}

first_indexed_at sits beside published_at on purpose: lead time is a field you can measure, not a claim you have to trust.

3. Ask what changed

This is the product. Send the cursor back and you get only what appeared since — and “nothing” is a normal, successful answer.

{
  "items": [],
  "has_more": false,
  "cursor": "c_eyJiIjoi…",
  "freshness": "stale"
}

An empty items is not an error and should not be retried. Report it plainly and store the new cursor.

4. Use it from an agent

The same capabilities are published as tool definitions, so an agent framework can call them without you writing a client. GET /v2/tools returns OpenAI function-call shape;POST /mcp speaks MCP.

curl /api/v2/tools

{
  "mcpServers": {
    "newsgraph": {
      "url": "/api/mcp"
    }
  }
}

What there is not

• No key to obtain. One is optional and only raises the rate limit, from 120 requests a minute to 1200
• No article bodies, at any price
• No writes: every route is read-only
• No summary. A brief quotes the publisher’s own headlines — nothing is rewritten, because a brief that paraphrases is a brief that can be wrong
• No promise that every topic is current. Ingestion runs every fifteen minutes, but a check can fail — so read the freshness field rather than assuming, and report stale or unavailable as exactly that rather than as an outage