Currents News API Documentation

Search Endpoint

The Search Endpoint lets you query 26M+ articles from a broad global source catalog. This endpoint is designed for deep discovery, content analysis, and precise retrieval of historical or real-time news based on keywords or structured filters.

Planning a search-led product?

Use the Search News API overview when you are comparing keyword discovery, date-range search, history windows, and plan fit before wiring the endpoint into an app.

Search News API Overview RAG and LLM Tutorial Monitoring Tutorial Code Examples Compare Quotas

Endpoint

V1 (Stable):

https://api.currentsapi.services/v1/search

V2 (Canonical Taxonomy & Keyset Pagination):

https://api.currentsapi.services/v2/search
Version behavior: cursor is rejected on /v1/search and supported on /v2/search.
Category taxonomy: Use canonical V2 categories from /v2/available/categories on /v2/search. On /v1/search use legacy v1 categories (for example, technology or science instead of science_technology). Passing a v2-only category to v1 returns 400 Invalid parameters.

Query Parameters

keywords / query

Search for articles containing specific terms.

  • keywords: Standard term search (for example, technology).
  • query: Boolean syntax with AND, OR, NOT, quotes, and parentheses.
  • Precedence: If both are provided, keywords takes priority over query.

Non-ASCII query values must be URL-encoded in GET URLs. Most HTTP clients handle this automatically when you pass values through a params or query object.

Filtering

language

Filter by language code (default: en).

country

Filter by 2-letter country code.

category

Filter by one or more canonical V2 categories.

type

1 (news), 2 (articles), 3 (discussion).

Time Window

start_date

Search after this date (RFC 3339 / ISO-8601 parseable value).

end_date

Search before this date (RFC 3339 / ISO-8601 parseable value).

Domain Control

domain

Restrict search to one domain (for example, reuters.com).

domain_not

Exclude specific domains from results.

author

Case-insensitive exact author filter (validated in API test coverage).

Pagination

page_number

The page index (starts at 1, max 180).

page_size

Results per page (1 to 300, default 30; account-tier caps still apply).

cursor

(V2 Only) Keyset token for deep pagination without offsets.

Offset guardrail: requests where (page_number - 1) * page_size > 5000 are rejected.

Example Calls

Programming-language tabs for the same search request:

Request

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v1/search?keywords=technology&language=en&page_number=1&page_size=5"

Request

fetch("https://api.currentsapi.services/v1/search?keywords=technology&language=en&page_number=1&page_size=5", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
})
  .then((res) => res.json())
  .then((data) => console.log(data));

Request

import requests

res = requests.get(
  "https://api.currentsapi.services/v1/search",
  params={
    "keywords": "technology",
    "language": "en",
    "page_number": 1,
    "page_size": 5,
  },
  headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(res.json())

Request

library(httr)

res <- GET(
  "https://api.currentsapi.services/v1/search",
  query = list(
    keywords = "technology",
    language = "en",
    page_number = 1,
    page_size = 5
  ),
  add_headers(Authorization = "Bearer YOUR_API_KEY")
)
content(res, "parsed")

Boolean query example (matches test coverage):

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v1/search?query=(%22AI%22%20OR%20%22Machine%20Learning%22)%20AND%20NOT%20%22Ethics%22&language=en"

Non-ASCII keyword example:

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v1/search?keywords=Beyonc%C3%A9&language=en"

V2 search with canonical category:

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v2/search?keywords=Redwood%20Materials&language=en&country=US&category=science_technology"

V1 search with legacy category:

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v1/search?keywords=Redwood%20Materials&language=en&country=US&category=technology"

V2 cursor pagination flow:

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v2/search?keywords=technology&language=en&page_size=5"
curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.currentsapi.services/v2/search?keywords=technology&language=en&page_size=5&cursor=<cursor-from-previous-response>"
Copy the next_cursor value from the previous response and replace <cursor-from-previous-response>.

Response Object

  • status: ok or error.
  • page: Current page index.
  • next_cursor: (V2 Only) Token to fetch the next contiguous page, or null when exhausted.
  • news: List of articles with attributes: id, title, description, url, author, image, language, category, published.

Full Response Example (V2)

{
  "status": "ok",
  "news": [
    {
      "id": "61f50bbd-20ad-47a3-9d77-9f8e0a08f0ad",
      "title": "AI chip demand lifts quarterly guidance",
      "description": "Vendors reported stronger-than-expected demand...",
      "url": "https://example.com/markets/ai-chip-demand",
      "author": "Market Desk",
      "image": "https://example.com/images/ai-chip.jpg",
      "language": "en",
      "category": ["economy_business_finance", "science_technology"],
      "published": "2026-03-24 12:05:00 +0000"
    }
  ],
  "page": 1,
  "next_cursor": "eyJwIjoiMjAyNi0wMy0yNFQxMjowNTowMCswMDowMCIsImlkIjoiNjFmNTBiYmQtMjBhZC00N2EzLTlkNzctOWY4ZTBhMDhmMGFkIn0"
}