Quickstart - Bonai Docs

This guide gets you from zero to your first Bonai News API request. You’ll need an API key from the Bonai console. See getting started if you don’t have one yet.

Search for articles

The GET /search/articles endpoint is the fastest way to get results:

curl --request GET \
  --url "https://api.bonai.io/news/search/articles?query=technology" \
  --header "Authorization: Bearer YOUR_API_KEY"

The response is paginated:

{
  "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": 10,
    "total_pages": 1285,
    "has_more": true
  },
  "articles": [
    {
      "id": "3f9c2a7b8d1e4f5a6b7c8d9e",
      "title": "Example article title",
      "url": "https://example.com/article",
      "excerpt": "A short description of the article.",
      "thumbnail": "https://example.com/image.jpg",
      "language": "en",
      "paywall": false,
      "content_length": 4821,
      "date": "2026-07-30T09:00:00+00:00",
      "authors": ["Jane Doe"],
      "keywords": ["technology"],
      "translations": null,
      "publisher": {
        "name": "Example Publishing",
        "url": "https://example.com",
        "favicon": "https://example.com/favicon.ico"
      }
    }
  ]
}

Each article carries a stable id and, for non-English articles, a translations map with per-language titles and excerpts.

This response shape is for version 2026-08-01. If you’re using 2024-01-01 or earlier, the response uses a flat camelCase envelope (success, size, totalHits) and articles don’t have id or translations. See API versions for details.

Refine your search

Add filters to narrow results:

curl --request GET \
  --url "https://api.bonai.io/news/search/articles?query=ai&language=en&country=us&sort=date&limit=20" \
  --header "Authorization: Bearer YOUR_API_KEY"

query (required): the search text.
language: ISO language code, for example en.
country: country code, for example us.
publisher: filter by a publisher’s URL.
paywall: filter by paywall status (true or false).
from / to: date range for published articles.
sort: relevance or date.
page / limit: pagination. limit defaults to 25 and is capped by your plan.

curl --request GET \
  --url "https://api.bonai.io/news/trendings?topic=technology&language=en&country=us" \
  --header "Authorization: Bearer YOUR_API_KEY"

Fetch an article by ID

Articles include a stable id. Use it with GET /article instead of a URL:

curl --request GET \
  --url "https://api.bonai.io/news/article?id=3f9c2a7b8d1e4f5a6b7c8d9e" \
  --header "Authorization: Bearer YOUR_API_KEY"

Provide exactly one of id or url.

Next steps

Explore all endpoints in the API Reference.
Understand API versions, rate limits, and errors.
Connect AI tools with the MCP server.

​Search for articles

​Refine your search

​Get trending articles

​Fetch an article by ID

​Next steps

Search for articles

Refine your search

Get trending articles

Fetch an article by ID

Next steps