KontextNews

Endpoints

A read-only JSON API over the news corpus: articles, cross-source events, the entity graph, sources and search. Every endpoint requires X-API-Key except /v1/health. All data is served from the last 30 days.

Corpus

GET/v1/health

Liveness probe. No authentication.

{"status":"ok","service":"kontextnews","version":"1.0.0"}
GET/v1/stats

Aggregated corpus stats: sources, articles, events, entities, languages and per-region coverage. Counts reflect the served 30-day window.

{
  "sources": 265, "articles": 40737, "events": 1105, "entities": 89419, "languages": 43,
  "by_region": [
    {"region":"europe","sources":49,"articles":9440},
    {"region":"north_america","sources":31,"articles":3387}
  ]
}
GET/v1/articles

List articles, newest first, from the last 30 days.

categoryFilter by category.
domainFilter by industry domain.
regionFilter by region.
langFilter by language.
countryFilter by ISO 3166-1 alpha-2 country.
source_idFilter by originating source (UUID).
since / untilISO 8601 window (published at or after / at or before).
idsBulk fetch: comma-separated UUIDs (max 100).
sortpublished (default) or title.
limit / offset1 to 200, default 50 / pagination offset.
curl "https://api.kontextnews.online/v1/articles?category=ai&country=US&limit=2" \
  -H "X-API-Key: kn_..."
Validated filters: an unknown category, domain, region, lang, country or sort returns 422 with the accepted values, so a typo is never mistaken for "no results".
GET/v1/articles/{id}

One article with its sources, entities and events.

{
  "id": "5877259d-f521-4b08-b362-b4e2dd1209aa",
  "title": "...",
  "sources":  [{"name":"Techmeme","feed_url":"...","is_primary":true}],
  "entities": [{"type":"org","name":"OpenAI","canonical":"openai"}],
  "events":   [{"event_id":"...","title":"..."}]
}

Events

GET/v1/events

Cross-source events, ordered by source count.

category / domain / regionFilters.
sinceISO 8601; events with activity at or after.
idsBulk fetch: comma-separated UUIDs (max 100).
sortsources (default), recent or score.
limit / offset1 to 200, default 50 / pagination offset.
{
  "id": "a61f1d35-30e0-4a90-b3e9-ad1ffc68a61d",
  "title": "Daniil Medvedev disqualified from China Open after hitting spectator in face with ball",
  "article_count": 4, "source_count": 4, "score": 4.0, "status": "open",
  "first_seen": "2026-10-05T16:13:32+00:00", "last_seen": "2026-10-05T19:42:28+00:00"
}
GET/v1/events/{id}

One event, enriched: its member articles, the entities it involves, and a timeline (each article with its source, the cross-source picture).

{
  "id": "...", "title": "...", "source_count": 4,
  "articles": [{"id":"...","title":"...","url":"...","source_id":"...","published_at":"..."}],
  "entities": [{"id":"...","type":"person","name":"Daniil Medvedev","salience":0.8}],
  "timeline": [{"published_at":"...","title":"...","url":"...","source":"Reuters","is_primary":true}]
}
GET/v1/events/{id}/entities

The entities of an event, by salience.

GET/v1/events/{id}/related

Related events that share entities with this one, ranked by how many entities they share.

[{"id":"...","title":"...","last_seen":"...","source_count":3,"shared":4}]

Entity graph

GET/v1/entities

Search and list entities (people, organisations, places).

typeperson, org, place or other.
qName search (trigram + substring).
limit / offset1 to 100, default 20 / pagination offset.
[{"id":"...","type":"org","name":"OpenAI","canonical":"openai","article_count":312,"event_count":44}]
GET/v1/entities/{id}

One entity with its articles, its events, and the entities it co-occurs with (the graph edges).

{
  "id": "...", "type": "org", "name": "OpenAI", "article_count": 312, "event_count": 44,
  "articles": [{"id":"...","title":"...","published_at":"..."}],
  "events":   [{"id":"...","title":"...","source_count":7}],
  "related":  [{"id":"...","type":"person","name":"Sam Altman","shared":118}]
}
GET/v1/entities/{id}/articles

The entity's articles (paginated).

GET/v1/entities/{id}/events

The entity's events.

GET/v1/entities/{id}/related

Entities that co-occur with this one, ranked by shared articles. This is the knowledge-graph edge.

Sources

GET/v1/sources

The source registry, ordered by authority.

regionFilter by region.
lang / category / domainFilters.
authority1 to 5.
include_disabledInclude disabled feeds, default false.
curl "https://api.kontextnews.online/v1/sources?region=europe&authority=5" \
  -H "X-API-Key: kn_..."

Search

GET/v1/search

Hybrid full-text and fuzzy search. Filters: category/domain/region/lang/since; sort=relevance (default) or date; limit/offset. See Search & ranking.