DocumentationStable/v1

Customer Guide: News API

Fetch curated articles, track clustered news events, inspect pipeline logs, and review request metrics. Every endpoint lives under /v1.

api.newsapi.oneTLS · REST · JSON

Contentstap to open

Overview

Pull structured news articles, cluster them into events, and analyze request patterns. Use these endpoints to power dashboards, alerts, or enrichment pipelines.

Base URL and Versioning

Default base URL: https://newsapi.one
API paths are namespaced under /v1.

Authentication

Most endpoints require an API key. Send it via header X-API-KEY: <your-key> (preferred) or query param ?apiKey=<your-key>.

Public endpoints (no key required)

/v1/health/**

Unauthorized responses

Invalid/missing keys return 401 Unauthorized with message Unauthorized: Missing or invalid API key.

Getting an API Key

Keys are generated when you create an account in newsapi.one.
The API key is visible in your account section.
Keep it secure: it’s the credential for authenticated calls.

Response Envelope

All responses share a common envelope:

jsonAPI Docs

{
  "status": "ok | error",
  "message": "string or null",
  "data": {}
}

Paginated collections are returned in data as:

jsonAPI Docs

{
  "samples": [ /* items */ ],
  "totalItems": 123,
  "totalPages": 13,
  "currentPage": 0,
  "pageSize": 10
}

Default pagination

page=0, size=10, sort=DESC. sort accepts ASC or DESC (case-insensitive).

Quick Start

Run these commands from any terminal to validate connectivity.

curl

bashAPI Docs

# 1) Health check (no key)
curl https://newsapi.one/v1/health

# 2) Fetch news
curl -H "X-API-KEY: <key>" "https://newsapi.one/v1/news?size=5"

# 3) Fetch events by category
curl -H "X-API-KEY: <key>" "https://newsapi.one/v1/events/by-category?value=politics"

# 4) View your request metrics (admin-scoped)
curl "https://newsapi.one/v1/auth/logs/filtered?apiKey=<key>&adminKey=<admin-key>"

# 5) Validate your key works
curl -H "X-API-KEY: <key>" https://newsapi.one/v1/test/secured

Articles

Structured articles enriched with sentiment scores and topics.

Supported fields

id, title, url, summary, text, source, scrapedAt, topic, sentiment {label, score}, sample

Method	Path	Description	Key Query Params / Body
GET	/v1/news	Paginated list sorted by scrapedAt	page, size, sort
GET	/v1/news/by-topic	Filter by exact topic	value (topic), page, size, sort
GET	/v1/news/by-date	Filter by scrape date (UTC)	value (yyyy-MM-dd), page, size, sort
GET	/v1/news/by-title	Case-insensitive title match	value (substring), page, size, sort
GET	/v1/news/{id}	Fetch a single article	—

Example response

jsonAPI Docs

{
  "status": "ok",
  "message": "Paginated news articles",
  "data": {
    "samples": [
      {
        "id": "664f8b...",
        "title": "Central bank signals rate pause",
        "url": "https://news.example.com/...",
        "summary": "Short abstract...",
        "text": "Full article text...",
        "source": "Reuters",
        "scraped_at": "2024-05-24T12:01:00Z",
        "topic": "economy",
        "sentiment": { "label": "neutral", "score": 0.11 },
        "sample": "..."
      }
    ],
    "totalItems": 1200,
    "totalPages": 600,
    "currentPage": 0,
    "pageSize": 2
  }
}

Events

Clustered, deduplicated news events with geocoding, tags, and lifecycle status. Event list endpoints sort by firstSeenAt.

Key fields (high-level)

id, label, summary, category, language, location, lat, lng, url, country, region, source, tags[], firstSeenAt, lastSeenAt, articleIds[], importanceScore, status, verified

Method	Path	Description	Key Query Params / Body
GET	/v1/events	Paginated events	page, size, sort
GET	/v1/events/by-category	Filter by category	value, page, size, sort
GET	/v1/events/by-date	Filter by firstSeenAt day	value (yyyy-MM-dd), page, size, sort
GET	/v1/events/by-status	Filter by lifecycle/status	value, page, size, sort
GET	/v1/events/{id}	Single event DTO	—
POST	/v1/events	Create an event	JSON body (full or partial)
PUT	/v1/events/{id}	Partial update (non-null fields are patched)	JSON body
DELETE	/v1/events/{id}	Delete an event	—
GET	/v1/events/raw	Raw events (un-enriched) sorted by timestamp	page, size, sort
GET	/v1/events/raw/{id}	Single raw event	—

Event creation example

bashAPI Docs

curl -X POST -H "Content-Type: application/json" \
  -H "X-API-KEY: <key>" \
  -d '{
    "label": "Wildfire grows near city limits",
    "summary": "Evacuations underway as crews battle blaze.",
    "category": "disaster",
    "language": "en",
    "location_name": "Valencia, Spain",
    "lat": 39.47,
    "lon": -0.38,
    "url": "https://news.example.com/wildfire",
    "tags": ["wildfire","evacuation"],
    "status": "active",
    "verified": true
  }' \
  http://localhost:8080/v1/events

Pipeline Logs

Operational audit trail for ingestion and enrichment steps. Lists are sorted by ts.

Fields

id, ts, actor, action, articleId, eventId, status, details{}, errorMessage

Method	Path	Description	Key Query Params / Body
GET	/v1/pipeline-logs	Paginated logs	page, size, sort
GET	/v1/pipeline-logs/by-actor	Filter by actor/service	value, page, size, sort
GET	/v1/pipeline-logs/by-action	Filter by action	value, page, size, sort
GET	/v1/pipeline-logs/by-status	Filter by status	value, page, size, sort
GET	/v1/pipeline-logs/by-article	Logs for an article	value (articleId), page, size, sort
GET	/v1/pipeline-logs/by-event	Logs for an event	value (eventId), page, size, sort
GET	/v1/pipeline-logs/by-date	Filter by day	value (yyyy-MM-dd), page, size, sort
GET	/v1/pipeline-logs/{id}	Single log entry	—

API-Key Metrics and Logs

Two endpoints surface per-key request analytics.

Basic (no admin key required)

GET /v1/auth/logs?apiKey=<key>&page=0

Returns recent requests for the given key (10 per page) sorted by timestamp.

Filtered with aggregates (admin key required)

GET /v1/auth/logs/filtered?apiKey=<key>&page=0&adminKey=<admin-key>&date=2024-05-24&success=true

Optional filters: date (yyyy-MM-dd), success (true/false).
Response data includes pagination plus successCount, failureCount, and averageDurationMillis.

RequestLog fields

path, method, ip, apiKey, timestamp, success, statusCode, errorMessage, durationMillis

Health and Test Endpoints

/v1/health (no key): composite health status.
/v1/test/public (no key): connectivity check.

Common Problems & Troubleshooting

401 Unauthorized: Ensure X-API-KEY header is present, key is active, and proxies aren’t stripping headers; for /v1/auth/logs/filtered also supply a valid adminKey.

400 Bad Request on date filters: Use yyyy-MM-dd (UTC), e.g. value=2024-05-24.

Empty pages: page is zero-based; ensure size > 0.

CORS preflight failures: Auth endpoints only allow origin https://www.newsapi.one.

404 Not Found: IDs must match exactly; articles/events/pipeline logs are separate collections.

Slow responses: Lower size, filter by date/category/topic, or fetch by ID.

Errors and Validation

401 Unauthorized: missing/invalid API key.
404 Not Found: unknown IDs.
400 Bad Request: invalid admin key or malformed bodies (e.g., date format).
All errors respect the envelope with status: "error" and a message.

CORS

Articles, events, and pipeline logs allow all origins (*).

Helpful Conventions

Dates: yyyy-MM-dd parsed in UTC; full-day coverage (inclusive start, exclusive next-day).
Sorting: sort=ASC|DESC sorts by scrapedAt (articles), firstSeenAt (events), or ts (pipeline logs).
Partial updates: PUT /v1/events/<id> only replaces non-null provided fields.