> ## 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 Google News API

The Google 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/google-news/search?query=technology" \
  --header "api-key: YOUR_API_KEY" \
  --header "api-version: 2026-05-25"
```

When the header is omitted, the API defaults to the latest version.

## Current version

The latest version is **`2026-05-25`**. It includes search, topics, frontpage, stories, publications, and retrieve endpoints.

## Legacy versions

Two older versions remain available for existing integrations:

* `2024-01-01`: legacy search and topic-headlines contracts.
* `2022-01-01`: the original search contract.

These versions use different parameter names and response shapes. They are maintained for compatibility only. New integrations should target the latest version.

<Note>
  New endpoints 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-05-25` in a staging environment.
2. Review the response shapes: the latest version uses the `metadata` / `parameters` / `news_articles` envelope and snake\_case fields.
3. Update your code and roll out.

The API Reference documents the latest version only.