Migration guide

Familiar with v1 or v2? The date-based versions map to: v1 = 2022-01-01, v2 = 2024-01-01, v3 = 2026-08-01. This guide uses both naming schemes.

Version comparison

	v1 (`2022-01-01`)	v2 (`2024-01-01`)	v3 (`2026-08-01`)
Envelope	`{ status, totalResults, articles }`	`{ success, totalHits, data }`	`{ metadata, parameters, articles }`
Search endpoint	`/search`	`/search/articles`	`/search/articles`
Article `id`	No	No	Yes
Article `translations`	No	No	Yes
Error format	`{ status: "error", code }`	`{ success: false, code }`	`{ metadata, errors }`
Pagination	`totalResults`	`totalHits`, `hitsPerPage`, `totalPages`	`total_hits`, `hits_per_page`, `total_pages`

Migrating from v1 to v2

What changed

Endpoint: /search → /search/articles
Query parameter: q → query
Response envelope: { status, totalResults, articles } → { success, totalHits, data }
Article fields: published_date → date, author → authors, description → excerpt
Error format: { status: "error", code } → { success: false, code }

Before (v1)

curl --request GET \
  --url "https://api.bonai.io/news/search?q=technology&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "api-version: 2022-01-01"

{
  "status": "ok",
  "totalResults": 12843,
  "articles": [
    {
      "title": "Example article",
      "url": "https://example.com/article",
      "published_date": "2026-07-30T09:00:00+00:00",
      "author": ["Jane Doe"],
      "description": "A short description."
    }
  ]
}

After (v2)

curl --request GET \
  --url "https://api.bonai.io/news/search/articles?query=technology&country=us&language=en" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "api-version: 2024-01-01"

{
  "success": true,
  "totalHits": 12843,
  "hitsPerPage": 25,
  "page": 1,
  "totalPages": 514,
  "data": [
    {
      "title": "Example article",
      "url": "https://example.com/article",
      "date": "2026-07-30T09:00:00+00:00",
      "authors": ["Jane Doe"],
      "excerpt": "A short description."
    }
  ]
}

Code changes

Before (v1):

const res = await fetch('https://api.bonai.io/news/search?q=technology');
const data = await res.json();
// data.status === 'ok'
// data.totalResults
// data.articles[0].published_date
// data.articles[0].author // array
// data.articles[0].description

After (v2):

const res = await fetch('https://api.bonai.io/news/search/articles?query=technology');
const data = await res.json();
// data.success === true
// data.totalHits
// data.data[0].date
// data.data[0].authors // array
// data.data[0].excerpt

Migrating from v2 to v3

What changed

Response envelope: { success, totalHits, data } → { metadata, parameters, articles }
Article fields: Added id and translations
Error format: { success: false, code } → { metadata, errors }
Pagination: totalHits → total_hits, hitsPerPage → hits_per_page

Before (v2)

{
  "success": true,
  "totalHits": 12843,
  "hitsPerPage": 25,
  "page": 1,
  "totalPages": 514,
  "data": [
    {
      "title": "Example article",
      "url": "https://example.com/article",
      "date": "2026-07-30T09:00:00+00:00"
    }
  ]
}

After (v3)

{
  "metadata": {
    "id": "0a1b2c3d-4e5f-6789-8abc-def012345678",
    "took_ms": 42,
    "timestamp": "2026-08-01T09:00:00Z"
  },
  "parameters": {
    "query": "technology"
  },
  "pagination": {
    "total_hits": 12843,
    "page": 1,
    "hits_per_page": 25,
    "total_pages": 514,
    "has_more": true
  },
  "articles": [
    {
      "id": "3f9c2a7b8d1e4f5a6b7c8d9e",
      "title": "Example article",
      "url": "https://example.com/article",
      "date": "2026-07-30T09:00:00+00:00",
      "translations": null
    }
  ]
}

Code changes

Before (v2):

const res = await fetch('https://api.bonai.io/news/search/articles?query=technology');
const data = await res.json();
// data.success === true
// data.totalHits
// data.data[0].title

After (v3):

const res = await fetch('https://api.bonai.io/news/search/articles?query=technology');
const data = await res.json();
// data.metadata.id
// data.pagination.total_hits
// data.articles[0].title
// data.articles[0].id // new
// data.articles[0].translations // new

Migrating from v1 to v3 (skip v2)

If you’re on v1 and want to go directly to v3, combine both migrations:

Change endpoint: /search → /search/articles
Change query parameter: q → query
Update response parsing: { status, totalResults, articles } → { metadata, parameters, articles }
Update article fields: published_date → date, author → authors, description → excerpt
Handle new fields: id, translations
Update error handling: { status: "error", code } → { metadata, errors }

Testing checklist

After migrating, verify:

Requests include the api-version header with the target version
Response parsing uses the new envelope structure
Article field names match the new schema
Error handling uses the new error format
Pagination uses the new field names
New fields (id, translations) are handled gracefully (can be null)

Need help?

If you run into issues during migration, check the API versions page for more details or reach out to support.

Guides

API Reference

Version comparison

Migrating from v1 to v2

What changed

Before (v1)

After (v2)

Code changes

Migrating from v2 to v3

What changed

Before (v2)

After (v3)

Code changes

Migrating from v1 to v3 (skip v2)

Testing checklist

Need help?

​Version comparison

​Migrating from v1 to v2

​What changed

​Before (v1)

​After (v2)

​Code changes

​Migrating from v2 to v3

​What changed

​Before (v2)

​After (v3)

​Code changes

​Migrating from v1 to v3 (skip v2)

​Testing checklist

​Need help?

Version comparison

Migrating from v1 to v2

What changed

Before (v1)

After (v2)

Code changes

Migrating from v2 to v3

What changed

Before (v2)

After (v3)

Code changes

Migrating from v1 to v3 (skip v2)

Testing checklist

Need help?