Skip to main content
The Bonai News API is versioned with the api-version header using dated versions (YYYY-MM-DD). Versions are backward-compatible snapshots of the API contract.

​
Selecting a version

Send the api-version header with the version you want:
When the header is omitted, the API defaults to the latest version.

​
Current version

The latest version is 2026-08-01. It includes search, publishers, article content, random articles, trending topics, and info endpoints. In this version:
  • Responses use a snake_case envelope with metadata, parameters, pagination, and resource-named keys.
  • Articles expose a stable id (when your plan includes it) and translations for non-English articles.
  • GET /article accepts exactly one of id or url.

​
Legacy versions

Older versions remain available for existing integrations:
  • 2024-01-01: uses a camelCase envelope (success, size, totalHits, …) and does not expose article id or translations.
  • 2022-01-01: legacy search and top-headlines contracts.
These versions use different response shapes. They are maintained for compatibility only. New integrations should target the latest version.
New fields are only available in the version where they were introduced. Requesting a route that doesn’t exist in your selected version returns a 404.

​
Upgrading

To upgrade to the latest version:
  1. Switch the api-version header to 2026-08-01 in a staging environment.
  2. Review the response shape: results are now wrapped in a metadata / parameters / pagination envelope with snake_case field names and resource-named keys (articles, article, publishers, topics, countries, languages).
  3. Handle the new id and translations fields on articles where your plan exposes them.
  4. Update your code and roll out.
The API Reference documents the latest version only.