{"openapi":"3.1.0","info":{"title":"NewsAgent Data API","description":"Structured Russian + English news API with urgency scoring, political lean classification, and event clustering. Thousands of sources across RSS feeds and live Telegram channels (see /public/stats for live counts). All endpoints except /public/* require an X-API-Key header. Rate limits: demo 100 req/day, starter 10k/day, standard 100k/day, pro unlimited. Burst protection: 60 req/min per key. Get a free API key at https://newsagentdata.com","version":"1.2.0"},"paths":{"/v1/feed":{"get":{"summary":"Feed","description":"Paginated news feed. Supports filtering by urgency score, language, audience, country, political lean, topic, and date range. Results ordered by fetched_at DESC. History window is tier-limited (demo: 1d, starter: 7d, standard: 90d, pro: unlimited).","operationId":"feed_v1_feed_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Page Size"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":0,"title":"Min Score"}},{"name":"max_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":10,"title":"Max Score"}},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Source"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"title":"Days"}},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filter by event type: war, disaster, crime, politics, economy, health, tech, other","title":"Event Type"},"description":"Filter by event type: war, disaster, crime, politics, economy, health, tech, other"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Filter by language: ru or en","title":"Language"},"description":"Filter by language: ru or en"},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filter by audience: trading, media, academic, security, tech, politics","title":"Audience"},"description":"Filter by audience: trading, media, academic, security, tech, politics"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Filter by country code: ru, us, uk, eu, cn, ua, il, tr, de, fr, in, int, etc.","title":"Country"},"description":"Filter by country code: ru, us, uk, eu, cn, ua, il, tr, de, fr, in, int, etc."},{"name":"political_lean","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filter by political lean: state, liberal, conservative, opposition, nationalist, neutral","title":"Political Lean"},"description":"Filter by political lean: state, liberal, conservative, opposition, nationalist, neutral"},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Filter by topic: ukraine, middle_east, markets, crypto, oil_gas, rates, sanctions, mergers, terrorism, cyber, nuclear, ai, chips, space, regulation, elections, diplomacy, pandemic, health, climate, trade, defense, energy, agriculture, economy, tech, transport","title":"Topic"},"description":"Filter by topic: ukraine, middle_east, markets, crypto, oil_gas, rates, sanctions, mergers, terrorism, cyber, nuclear, ai, chips, space, regulation, elections, diplomacy, pandemic, health, climate, trade, defense, energy, agriculture, economy, tech, transport"},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"page":1,"page_size":50,"count":2,"articles":[{"id":184921,"title":"Удар по Харькову: 3 погибших, 12 раненых","source":"ТАСС","link":"https://tass.ru/...","fetched_at":"2026-06-04T12:31:05","urgency_score":9,"urgency_label":"Critical","cluster_id":1780434861,"cluster_size":7,"language":"ru","region":"rucis","event_type":"war","political_lean":"state","country_tags":["ru","ua"],"audience_tags":["media","security","politics"],"topic_tags":["ukraine"],"content_preview":"В результате удара по центру Харькова погибли трое мирных жителей..."},{"id":184920,"title":"Brent crude drops 2% on demand outlook","source":"Reuters","link":"https://reuters.com/...","fetched_at":"2026-06-04T12:29:44","urgency_score":6,"urgency_label":"Notable","cluster_id":1780434855,"cluster_size":3,"language":"en","region":"int","event_type":"economy","political_lean":"neutral","country_tags":["int"],"audience_tags":["trading"],"topic_tags":["oil_gas","markets"],"content_preview":"Oil prices fell on Thursday as traders weighed..."}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/breaking":{"get":{"summary":"Breaking","description":"Breaking news feed — articles with urgency score ≥ 7 (default), ordered by score then recency. Time window capped by tier history limit. Supports audience, country, political lean, and topic filters.","operationId":"breaking_v1_breaking_get","parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":168,"minimum":1,"default":24,"title":"Hours"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":7,"default":7,"title":"Min Score"}},{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by audience: trading, media, academic, security, tech, politics","title":"Audience"},"description":"Filter by audience: trading, media, academic, security, tech, politics"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by country code: ru, us, uk, eu, cn, ua, il, tr, de, fr, in, int, etc.","title":"Country"},"description":"Filter by country code: ru, us, uk, eu, cn, ua, il, tr, de, fr, in, int, etc."},{"name":"political_lean","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by political lean: state, liberal, conservative, opposition, nationalist, neutral","title":"Political Lean"},"description":"Filter by political lean: state, liberal, conservative, opposition, nationalist, neutral"},{"name":"topic","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by topic: ukraine, middle_east, markets, crypto, oil_gas, rates, sanctions, mergers, terrorism, cyber, nuclear, ai, chips, space, regulation, elections, diplomacy, pandemic, health, climate, trade, defense, energy, agriculture, economy, tech, transport","title":"Topic"},"description":"Filter by topic: ukraine, middle_east, markets, crypto, oil_gas, rates, sanctions, mergers, terrorism, cyber, nuclear, ai, chips, space, regulation, elections, diplomacy, pandemic, health, climate, trade, defense, energy, agriculture, economy, tech, transport"},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"count":1,"articles":[{"id":184921,"title":"Missile strike on Kyiv: 5 killed, 18 wounded","source":"Kyiv Independent","link":"https://kyivindependent.com/...","fetched_at":"2026-06-04T12:31:05","urgency_score":10,"urgency_label":"Critical","cluster_id":1780434861,"cluster_size":12,"language":"en","region":"rucis","event_type":"war","political_lean":"liberal","country_tags":["ua","ru"],"audience_tags":["media","security","politics"],"topic_tags":["ukraine"],"content_preview":"A Russian missile strike on central Kyiv killed at least 5 people..."}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audience/{audience}":{"get":{"summary":"Audience Feed","description":"Dedicated news feed pre-filtered for a specific audience segment. Valid values: trading, media, academic, security, tech, politics. Ordered by urgency score DESC then recency.","operationId":"audience_feed_v1_audience__audience__get","parameters":[{"name":"audience","in":"path","required":true,"schema":{"type":"string","title":"Audience"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Page Size"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":0,"title":"Min Score"}},{"name":"hours","in":"query","required":false,"schema":{"type":"integer","maximum":720,"minimum":1,"default":24,"title":"Hours"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"get":{"summary":"Search","description":"Full-text search across article titles and content. Searches both Russian and English text. Results ordered by urgency score DESC. History window is tier-limited.","operationId":"search_v1_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Q"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":0,"title":"Min Score"}},{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"default":30,"title":"Days"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Page Size"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/export/jsonl":{"get":{"summary":"Export Jsonl","description":"Bulk export as JSONL (newline-delimited JSON). Each line is one article with all metadata fields. Streamed response — suitable for loading into databases, RAG pipelines, or ML training sets. History window is tier-limited.","operationId":"export_jsonl_v1_export_jsonl_get","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":7,"title":"Days"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":0,"title":"Min Score"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stream":{"get":{"summary":"Stream","description":"Server-Sent Events (SSE) stream of breaking articles in real time. Polls every 30s and pushes new articles above min_score threshold. Session limited to 30 minutes. Pro tier and above only.","operationId":"stream_v1_stream_get","parameters":[{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":7,"title":"Min Score"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhook":{"post":{"summary":"Register Webhook","description":"Register a webhook URL. Breaking articles (score ≥ 7) will be POSTed within 60s.","operationId":"register_webhook_v1_webhook_post","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","description":"HTTPS URL to receive POST requests","title":"Url"},"description":"HTTPS URL to receive POST requests"},{"name":"secret","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional HMAC signing secret","title":"Secret"},"description":"Optional HMAC signing secret"},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"Get Webhook","description":"View your current webhook registration.","operationId":"get_webhook_v1_webhook_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Webhook","description":"Unregister your webhook.","operationId":"delete_webhook_v1_webhook_delete","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sources":{"get":{"summary":"List Sources","description":"List all active sources with metadata. Filter by audience, country, language, or type (rss/tg).","operationId":"list_sources_v1_sources_get","parameters":[{"name":"audience","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience"}},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"}},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string","default":"","title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"total":466,"sources":[{"name":"ТАСС","type":"rss","language":"ru","country":["ru"],"audience":["media","politics"],"political_lean":"state","article_count":4821},{"name":"Kyiv Independent","type":"tg","language":"en","country":["ua"],"audience":["media","security"],"political_lean":"liberal","article_count":1203}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/stats":{"get":{"summary":"Dataset Stats","description":"Public dataset statistics — total articles, breaking events count, source count, and articles added today. No authentication required.","operationId":"public_stats_public_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/public/country/{code}":{"get":{"summary":"Public Country Sample","description":"Recent article sample + count for one country (ISO-2 code). No auth. Source and link are masked (public teaser). Powers the coverage page.","operationId":"public_country_public_country__code__get","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","title":"Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/sample":{"get":{"summary":"Public Country Sample","description":"A few recent sample articles for a given country (ISO-2 code). No authentication. Source and link are masked — preview only.","operationId":"public_sample_public_sample_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","maxLength":3,"title":"Country"}},{"name":"topic","in":"query","required":false,"schema":{"type":"string","maxLength":24,"title":"Topic"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":60,"title":"Q"}},{"name":"min_urgency","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":0,"default":0,"title":"Min Urgency"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"default":3,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/status":{"get":{"summary":"Public Status","description":"Live operational status — API health, ingestion freshness, and throughput. No authentication required.","operationId":"public_status_public_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/public/sources":{"get":{"summary":"Public Source Breakdown","description":"Aggregate source coverage — counts by country, language, and type. No source identities or handles exposed. No authentication required. 10-minute cache.","operationId":"public_sources_public_sources_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/public/breaking":{"get":{"summary":"Public Breaking News","description":"Most recent breaking articles (urgency score ≥ 5) from the last hour. No authentication required. Use this to preview live data before signing up.","operationId":"public_breaking_public_breaking_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/live-feed":{"get":{"summary":"Public Live Feed","description":"Breaking articles (urgency score ≥ min_score) from the last 24 hours, WITH source names and links. No authentication required. Powers the public /news feed page.","operationId":"public_live_feed_public_live_feed_get","parameters":[{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":7,"title":"Min Score"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/article/{news_id}":{"get":{"summary":"Public Article","description":"Full content of a single article by id, WITH source name and link. No authentication required. Powers the public /news reader view.","operationId":"public_article_public_article__news_id__get","parameters":[{"name":"news_id","in":"path","required":true,"schema":{"type":"integer","title":"News Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/card.svg":{"get":{"summary":"Live Breaking Card (SVG)","description":"Self-updating SVG card of the latest breaking headlines. No auth. Designed for embedding (README, status pages). Source identities are not exposed.","operationId":"public_card_svg_public_card_svg_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":6,"minimum":1,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/public/banner.svg":{"get":{"summary":"Live Banner (SVG)","description":"Self-updating brand banner with live coverage numbers (countries, languages, sources, articles). No auth. Designed for embedding (GitHub README).","operationId":"public_banner_svg_public_banner_svg_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}