API v2 · Release 2.1.3 · 16 read-only routes · 9 MCP tools

URSY.news API v2

Publisher-feed headlines, feed-supplied excerpts, links and metadata. URSY does not fetch article pages, store or serve full article bodies.

The v2 API adds conservative event grouping above the headline archive. The complete v1 API and simple WordPress API keep their existing contracts. Every event label is a retained publisher headline with attribution; publisher counts describe observed coverage, not agreement.

v2 manifest · OpenAPI 3.1 · Capability manifest · Collection health

Quick start

18 curated feeds from 12 publisher organisations.

Try the live API

• Five events covered by multiple publishers
• Five recent stories with provenance and event IDs
• Search events, headlines, publishers and topics
• Feed health and a starting change checkpoint

List requests accept up to 50 records. Events support source, topic, q, from, to, min_publishers and changed_since. Dates are UTC; from is inclusive and to exclusive. Follow the returned next_url to continue with the same filters. Unknown or duplicate parameters are rejected. Cursors continue a changing archive; they do not freeze its contents.

Poll what changed

To start watching new observations, first request GET /api/v2/status and follow changes.poll_url. Its changes.checkpoint skips earlier committed history. Status may be cached briefly, so deduplicate observations by their sequence. MCP clients can obtain the same checkpoint from get_status.

To read the available history from its beginning, start with GET /api/v2/changes:

GET /api/v2/changes?limit=50
GET /api/v2/changes?since=RETURNED_CHECKPOINT&limit=50

Process each page before storing its checkpoint. Follow pagination while has_more is true; an empty page returns the same checkpoint. Checkpoints identify committed observations and corrections, not publication time. Reuse ETag with If-None-Match and respect Cache-Control and Retry-After. Default origin capacity is 300 requests/minute shared with v1, MCP and Nicola metadata calls.

Read-only MCP

Send JSON-RPC POST to https://ursy.news/mcp/news. The server supports protocol versions 2026-07-28 and 2025-11-25, using stateless JSON responses. The existing estate MCP directory remains available.

• search_news — Search publisher-feed headlines and excerpts, with separate events, stories, sources and topics.
• latest_events — Recent conservative event groups. Default min_publishers=1 includes standalone groups; coverage is not consensus.
• get_event — Read an event with member IDs, publisher diversity and grouping provenance. Use the REST members/compare links for full paginated descriptors.
• get_event_timeline — Read append-only URSY observations and corrections, not real-world chronology.
• get_story — Read one attributed feed headline and excerpt descriptor; never an article body.
• get_sources — List curated feeds, publisher identities, terms review records and access caveats.
• get_source — Read one feed identity, provenance, rights review and collection health.
• what_changed — Resume incremental observations. Process the page before saving its returned checkpoint.
• get_status — Read collection, grouping, rights review and timestamp health, plus a starting changes checkpoint.

For the 2025-11-25 protocol, initialize once with that version, then call tools/list or tools/call. Include Content-Type: application/json, Accept: application/json, text/event-stream and MCP-Protocol-Version: 2025-11-25.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"news-reader","version":"1.0"}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"latest_events","arguments":{"limit":5,"min_publishers":2}}}

For 2026-07-28, use server/discover and per-request protocolVersion and clientCapabilities in params._meta, with matching MCP-Protocol-Version, Mcp-Method and (for tools/call) Mcp-Name headers. No account, cookie or reading history is required. Tools perform no network article fetching or write operations.

Provenance and limitations

New stories preserve raw publisher timestamps and flag dates more than five minutes after retrieval. Missing or invalid dates use a documented collection-time fallback. Earlier records whose basis cannot be proved remain unknown_legacy. Timelines describe URSY feed observations and explicit grouping corrections; they are not necessarily the chronology of a real-world event. Empty or merged groups retain their stable IDs and correction history without retaining pruned publisher text.

Story and event topic provenance identifies the source-feed category. It is not an inferred article subject. Successful v2 responses carry X-URSY-News-API-Version; the manifest and OpenAPI document the same release version.

Use original publisher links, preserve publisher attribution and access labels, and keep sponsorship separate. API availability grants no redistribution rights over publisher text or images. No article body, synthetic summary, truth probability or ideological score is supplied.

Canonical records and warnings

Record properties below come from the same schema owner used by the runtime serializers, OpenAPI and MCP outputs.

Developer manifest · Source policy · Grouping methodology · Corrections · Release changelog

Queries match retained headlines and feed excerpts. The query limit is 200 UTF-8 bytes, so non-ASCII characters may consume more than one byte. Deduplicate stories by ID, events by ID and updated_at, and changes by sequence.