# Event Registry (NewsAPI.ai)

> News intelligence API. Search global news articles, retrieve deduplicated event clusters,
> resolve named entities to URIs, and read sentiment and category enrichment across 150,000+
> sources in 60+ languages, with a historical archive back to 2014.

GENERATED by API Evangelist on 2026-08-13 from this repository's apis.yml and artifacts.
Event Registry does NOT publish an llms.txt: https://newsapi.ai/llms.txt and
https://eventregistry.org/llms.txt both return the site's single-page-application HTML shell,
byte-identical to the shell served for a known-nonexistent path. Treat this file as API
Evangelist's summary, not the provider's.

## How to call it

- Base URL: https://eventregistry.org/api/v1
- Every operation is a POST with a JSON body. There are no GET endpoints and no resource URLs.
- Auth: an `apiKey` field inside the JSON body (a query parameter of the same name also works).
  Get one at https://newsapi.ai/register — free plan, 2,000 searches, no credit card.
- Entity filters take opaque URIs, not names. Resolve a name to a URI with a suggest call
  FIRST, then pass the URI. Almost every real query is therefore a two-call sequence.
- Concurrency is capped at 5 simultaneous requests per account. Exceeding it returns HTTP 503
  immediately; requests are not queued. Make calls sequentially.
- Cost signal: responses carry `req-tokens` (tokens this request cost) and
  `x-ratelimit-remaining` (tokens left). There is no standard RateLimit header and no
  Retry-After.

## Operations

Articles
- searchArticles — POST /article/getArticles — search articles by concept, source, category,
  date, language, sentiment.
- getArticleDetails — POST /article/getArticle — full detail for up to 100 article URIs.
- getTopicPageArticles — POST /article/getArticlesForTopicPage — articles from a saved topic page.

Events (clusters of articles about one real-world happening — polled, not pushed)
- searchEvents — POST /event/getEvents
- getEventDetails — POST /event/getEvent
- getTopicPageEvents — POST /event/getEventsForTopicPage

Suggest (name to URI resolution — call these before filtering)
- suggestConcepts — POST /suggestConceptsFast
- suggestCategories — POST /suggestCategoriesFast
- suggestSources — POST /suggestSourcesFast
- suggestLocations — POST /suggestLocationsFast
- suggestAuthors — POST /suggestAuthorsFast

Usage
- getApiUsage — POST /usage — tokens used and remaining for the current key.

## Agent surface

- MCP server (first-party): `npx -y newsapi-mcp`, npm package `newsapi-mcp` v1.3.1
  (2026-03-18), MIT, https://github.com/EventRegistry/newsapi-mcp
  LOCAL STDIO ONLY — there is no hosted MCP endpoint. A human must install and run it, with
  a NewsAPI.ai key in the NEWSAPI_KEY environment variable, before an agent can use it.
  8 tools: search_articles, get_article_details, search_events, get_event_details,
  get_topic_page_articles, get_topic_page_events, suggest, get_api_usage.
  Protocol 2025-11-25, capabilities: tools + resources.
- Agent Skill (first-party): `/news` — skill/SKILL.md in the same repo, with 10 report
  templates (adverse media, company intel, economic, geopolitical, investing, political,
  research, sentiment, supply chain, findings). Saved verbatim in skills/.
- No A2A agent card. No hosted MCP. No /.well-known/ documents of any kind.

## Token efficiency (the provider's own recommended pattern)

suggest -> scan -> triage -> retrieve.
1. suggest({type: "concepts", prefix: "<name>"}) to get a URI.
2. search_articles({conceptUri, articlesCount: 100, articleBodyLen: 0,
   isDuplicateFilter: "skipDuplicates"}) — titles only, no bodies. Cheap.
3. Pick the URIs that matter.
4. get_article_details({articleUri: [...up to 100...]}) for full text on just those.

Costs: recent article search 1 token; historical article search 5 tokens per year queried;
recent event search 5 tokens; historical event search 20 tokens per year. Cache suggest
results — they are stable and the provider's own server caches them for 24 hours.

## Errors

- 400 invalid_param, 401/403 auth_error, 404 not_found, 429 rate_limit (quota — wait, do not
  hammer), 503 concurrent_limit (the 5-request cap), 5xx api_error.
- Envelope is a bespoke {error, message} JSON object. NOT RFC 9457 problem+json.
- Only 401 and 429 are declared in the OpenAPI; the rest come from the provider's own MCP
  error classifier.

## SDKs

- Python: `eventregistry` 9.1 (2023-06-23) — https://github.com/EventRegistry/event-registry-python
- Node.js: `eventregistry` 9.1.1 (2024-11-14) — https://github.com/EventRegistry/event-registry-node-js
- Both predate the 2026 parameter additions. The MCP server is the current first-party client.

## What does NOT exist

No webhooks, no streaming, no push. No GraphQL. No gRPC. No OAuth or OIDC. No CLI. No
embeddable UI components. No status page. No security.txt or vulnerability disclosure
program. No trust center or published certifications. No test/sandbox environment — the
"sandbox" at newsapi.ai/documentation/sandbox is a browser query builder that spends real
quota against live data.

## Links

- Product: https://newsapi.ai
- Documentation: https://newsapi.ai/documentation (JavaScript-rendered; not machine-readable)
- Sandbox / query builder: https://newsapi.ai/documentation/sandbox
- Pricing: https://newsapi.ai/plans
- Blog: https://newsapi.ai/blog/
- Terms: https://newsapi.ai/terms
- GitHub: https://github.com/EventRegistry
- Support: info@eventregistry.org