Pagination
List endpoints use limit and offset, and return Link and X-Total-Count headers.
| limit | Page size. Articles and events: 1 to 200 (default 50). Search: 1 to 100 (default 20). |
| offset | Number of records to skip, 0 to 10000. Default 0. |
Ordering
Ordering is deterministic, so paging is stable. List endpoints accept sort:
- Articles:
sort=published(default,published_atdescending) ortitle. - Events:
sort=sources(default),recentorscore. - Search:
sort=relevance(default, recency-weighted score) ordate. - Entities:
article_countdescending, then name.
Response headers
List responses carry ready-made navigation and the total match count:
Link: <https://api.kontextnews.online/v1/articles?limit=50&offset=150>; rel="next",
<https://api.kontextnews.online/v1/articles?limit=50&offset=50>; rel="prev"
X-Total-Count: 32324
Link (RFC 8288) preserves your filters in the next and prev URLs. X-Total-Count (the total matching rows) is returned by /v1/articles and /v1/events; /v1/search is rank-ordered and returns Link only. Reads also carry a weak ETag: send it back as If-None-Match and an unchanged page returns 304 with no body.
Example
curl "https://api.kontextnews.online/v1/articles?limit=50&offset=100" \ -H "X-API-Key: kn_..."
Follow rel="next" until it is absent. Equivalently, increase offset by limit each time, until you receive fewer rows than limit.