> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API versions

> How versioning works for the Bonai News API

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:

```bash theme={null}
curl --request GET \
  --url "https://api.bonai.io/news/search/articles?query=technology" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "api-version: 2026-08-01"
```

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.

<Note>
  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`.
</Note>

## 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.