Overview

The Neuvia API gives you a daily time series of news sentiment for any entity+concept pair, alongside Balanced Discoverable Media Sentiment (BDMS): a publisher-balanced reference built from discoverable news coverage, with a 95% confidence interval. The gap between a channel's sentiment and BDMS is its Channel Narrative Divergence (CND). All responses are JSON. Pass your API key as a Bearer token or query param. The base URL is https://neuvianews.com/api, so GET /v1/narratives means https://neuvianews.com/api/v1/narratives.

Authentication

Pass your API key in the Authorization header or as a query parameter:

bash
# Header (recommended)
curl -H "Authorization: Bearer nv_your_key" \
  https://neuvianews.com/api/v1/trending

# Query param
curl "https://neuvianews.com/api/v1/trending?api_key=nv_your_key"

Rate limits

Every response includes rate limit headers:

http
X-RateLimit-Limit: 20000
X-RateLimit-Used: 142
X-Plan: starter

Error format

Errors return a JSON object with an error field:

json
{
  "error": "Monthly call limit reached (20,000 calls).",
  "upgradeUrl": "https://neuvianews.com/#pricing"
}