API versions - Bonai Docs

Familiar with v1 or v2? The date-based versions map to: v1 = 2022-01-01, v2 = 2024-01-01, v3 = 2026-05-25. See the migration guide for upgrade steps.

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:

curl --request GET \
  --url "https://api.bonai.io/google-news/search?query=technology" \
  --header "Authorization: Bearer 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.

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.

API Reference by version

Use the version selector in the API Reference sidebar to switch between versions. Each version shows the endpoints and response shapes available in that version.

Response shape differences

The key difference between versions is the response envelope. Version 2024-01-01 and earlier use a flat camelCase envelope:

{
  "success": true,
  "size": 10,
  "totalHits": 842,
  "articles": [
    {
      "title": "Example technology headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z"
    }
  ]
}

Version 2026-05-25 uses a structured snake_case envelope:

{
  "metadata": {
    "id": "c1a2b3d4-e5f6-4789-8abc-def012345678",
    "total_hits": 842,
    "took_ms": 96,
    "timestamp": "2026-07-30T09:00:00Z"
  },
  "parameters": {
    "query": "technology",
    "country": "us",
    "language": "en"
  },
  "news_articles": [
    {
      "type": "article",
      "title": "Example technology headline",
      "url": "https://example.com/story",
      "date": "2026-07-30T08:00:00Z"
    }
  ]
}

Upgrading from `2024-01-01` to `2026-05-25`

Switch the api-version header to 2026-05-25 in a staging environment.
Update response parsing: results are now wrapped in metadata / parameters / news_articles instead of flat success / size / totalHits.
Handle the new type discriminator on news_articles items (articles, stories, storylines, social posts).
Update error handling: errors now use the metadata + errors envelope instead of { success: false, code, message, fields }.
Test and roll out.

See errors for the error envelope differences.

​Selecting a version

​Current version

​Legacy versions

​API Reference by version

​Response shape differences

​Upgrading from 2024-01-01 to 2026-05-25

Selecting a version

Current version

Legacy versions

API Reference by version

Response shape differences

Upgrading from `2024-01-01` to `2026-05-25`