API Documentation

Using an AI agent? Try the MCP server — query this API natively from Claude Desktop, Cursor or any MCP client.

A REST API for structured Russian & English news — every article urgency-scored, classified by political lean, event-clustered, and tagged. JSON in, JSON out.

Quickstart

Grab a free key (100 requests/day, no card), then make your first call. Base URL: https://api.newsagentdata.com

# 1. Get a free key: https://newsagentdata.com/signup/?plan=free
# 2. Call the feed
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.newsagentdata.com/v1/feed?language=en&min_score=6&page_size=5"

# Python
import requests
r = requests.get(
  "https://api.newsagentdata.com/v1/feed",
  headers={"X-API-Key": "YOUR_KEY"},
  params={"topic": "sanctions", "min_score": 7, "language": "ru"},
)
for a in r.json()["articles"]:
    print(a["urgency_score"], a["political_lean"], a["title"])

// JavaScript (fetch)
const r = await fetch(
  "https://api.newsagentdata.com/v1/feed?topic=sanctions&min_score=7",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const { articles } = await r.json();

Sample response

{
  "total": 184, "page": 1, "page_size": 5,
  "articles": [
    {
      "id": 521844,
      "title": "EU agrees 14th sanctions package targeting Russian LNG",
      "source": "Reuters", "link": "https://www.reuters.com/...",
      "urgency_score": 8, "urgency_label": "Breaking",
      "political_lean": "neutral",
      "topic_tags": ["sanctions", "oil_gas"],
      "country_tags": "ru,eu", "audience_tags": "trading,politics",
      "event_type": "economy", "language": "en",
      "cluster_id": 1781034992, "cluster_size": 27,
      "content_preview": "The European Union approved its 14th sanctions package...",
      "fetched_at": "2026-06-17T18:42:11Z"
    }
  ]
}

Authentication

Pass your key in the X-API-Key header on every /v1/* request. Missing or invalid keys return 401. The /public/* endpoints need no auth.

X-API-Key: nap_xxxxxxxxxxxxxxxxxxxxxxxxx

Errors

Standard HTTP status codes. Error bodies are JSON: {"detail": "..."}.

Code	Meaning
200	Success
401	Missing or invalid `X-API-Key`
403	Endpoint not available on your tier
422	Invalid query parameter
429	Daily quota or 60/min burst exceeded

Rate limits & tiers

Daily request quotas and history windows are tier-based. Burst is capped at 60 requests/minute per key. See full pricing.

Tier	Requests/day	History	Extras
free	100	1 day	metadata only
developer	5,000	7 days	source names & links
starter	10,000	7 days	source names & links
standard	100,000	90 days	full text · webhook · catalog
pro	unlimited	full archive	+ SSE · 500k export

Feed & breaking

GET/v1/feed

Paginated news feed. Filter by score, language, country, lean, topic, audience, event type, date range. Ordered newest first.

GET/v1/breaking

Breaking items only — urgency score ≥ 7 by default, ordered by score then recency.

GET /v1/feed?country=ru&topic=oil_gas&min_score=6&days=7&page=1&page_size=50

Search

GET/v1/search?q=

Full-text search across titles and content, Russian and English. Ordered by urgency. History window is tier-limited.

GET /v1/search?q=sanctions%20oil&language=en

Audience feeds

GET/v1/audience/{audience}

Pre-filtered feed for one audience: trading, media, academic, security, tech, politics.

Bulk export

GET/v1/export/jsonl

Streamed JSONL — one article per line, all metadata fields. Per-tier row caps (1k → 500k). Ideal for RAG stores, datasets, fine-tuning.

GET /v1/export/jsonl?language=ru&topic=sanctions&days=90

Real-time (SSE)

GET/v1/stream

Server-Sent Events stream of breaking articles, pushed in near real-time. Pro tier and above.

Webhooks

POST/v1/webhook?url=&secret=

Register an HTTPS endpoint to receive score ≥ 7 articles within 60s. HMAC-SHA256 signed (X-Signature). Standard tier and above.

GET/v1/webhook DELETE/v1/webhook

List or remove your registered webhook.

Sources & public

GET/v1/sources

Source catalog with metadata (type, language, country, audience, lean, article count). Standard tier and above.

GET/public/stats · /public/sources · /public/breaking · /public/status

No-auth endpoints for dataset stats, aggregate coverage, a recent-breaking preview, and live system status.

Query parameters

Param	Values	Description
language	ru · en	Filter by article language
min_score	0–10	Minimum urgency score
country	ISO-2 (ru, us, ua…)	Filter by ISO-2 country code
political_lean	state · official · centrist · liberal · conservative · nationalist · opposition · tabloid · neutral	Source editorial lean (9 categories)
topic	sanctions · ukraine · oil_gas · crypto · cyber · nuclear · elections … (18)	Topic tag
audience	trading · media · academic · security · tech · politics	Audience segment
event_type	war · economy · politics · crime · disaster · health · tech	Event classification
days	integer	Look-back window (capped by tier)
page / page_size	integer / 1–100	Pagination

Article schema

Every article returns the same structured object (19 fields):

Field	Type	Description
id	int	Unique article id
title	str	Headline
source	str	Outlet (paid tiers; null on free)
link	str	Original URL (paid tiers)
content / content_preview	str	Body (full text on standard+) / 200-char preview
urgency_score	int	0–10 urgency
urgency_label	str	Human label for the score
political_lean	str	9-category lean
topic_tags	list	Topic tags (18-tag taxonomy)
country_tags	str	ISO-2 country tags
audience_tags	str	Audience segments
event_type	str	Event classification
language	str	ru / en
cluster_id	int	Shared event id across outlets
cluster_size	int	How many sources covered it
region / category	str	Geographic region & category
fetched_at	datetime	Ingestion timestamp (UTC)

Want the interactive spec? The full OpenAPI / Swagger UI is at api.newsagentdata.com/docs.