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

# Migration guide

> Migrate between Bonai News API versions with before/after code examples

> [!NOTE]
>
> **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)

```bash theme={null}
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"
```

```json theme={null}
{
  "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)

```bash theme={null}
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"
```

```json theme={null}
{
  "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):**

```javascript theme={null}
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):**

```javascript theme={null}
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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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):**

```javascript theme={null}
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):**

```javascript theme={null}
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:

1. Change endpoint: `/search` → `/search/articles`
2. Change query parameter: `q` → `query`
3. Update response parsing: `{ status, totalResults, articles }` → `{ metadata, parameters, articles }`
4. Update article fields: `published_date` → `date`, `author` → `authors`, `description` → `excerpt`
5. Handle new fields: `id`, `translations`
6. 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](/news-api/api-version) for more details or reach out to support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.