Skip to main content

Documentation Index

Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://v3-api.newscatcherapi.com/api
Append the endpoint path to this base URL for every request. There is no sandbox environment — all requests run against production.

​
Authentication

Pass your API key in the x-api-token header on every request: 
x-api-token: YOUR_API_KEY
For implementation examples in all supported languages, see Authentication.

​
Request format

All endpoints support both GET and POST. When using POST, set Content-Type: application/json and pass parameters in the JSON request body. 
curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "renewable energy",
    "lang": "en",
    "page_size": 1
  }'
GETPOST
ParametersURL query stringJSON request body
URL length limitLimited (varies by client)None
Best forQuick testing and debuggingComplex filters, production integrations
For most production integrations, POST is the better choice — it avoids URL length limits and keeps parameters out of server logs and browser history.

​
Response format

All endpoints return JSON with the following top-level envelope: 
{
  "status": "ok",
  "total_hits": 10000,
  "page": 1,
  "total_pages": 100,
  "page_size": 100,
  "articles": [],
  "user_input": {}
}
The articles array contains the matched article objects. The full schema is available in each endpoint reference. The response also includes a user_input object that echoes the specified parameters and defaults as interpreted by the API — useful for debugging unexpected results.

​
Pagination

Two parameters control pagination:
ParameterDefaultMaximum
page1No hard limit, but results cap at 10,000 articles per request
page_size1001000
A query can return at most 10,000 articles per request. If total_hits is 10000, the actual match count is likely higher. To learn how to retrieve beyond this limit, see Retrieve large datasets.

​
Rate limits

Rate limits vary by subscription plan. Exceeding your limit returns a 429 status code. For plan-specific limits and retry guidance, see Rate limits.

​
Errors

All error responses use a consistent JSON envelope: 
{
  "message": "Invalid api key",
  "status_code": 401,
  "status": "Unauthorized"
}
For the full list of status codes and resolution steps, see Errors.

​
Endpoints

News API provides the following endpoints. All endpoints support both GET and POST methods.
EndpointDescription
/searchSearches for articles by keyword, phrase, or Boolean query. Supports filtering by language, country, source, date range, sentiment, NLP tags, and more.
/latest_headlinesReturns the most recent headlines published within a specified time window. Supports filtering by language, country, source, and NLP attributes.
/breaking_newsReturns actively breaking news events, each with a configurable number of top representative articles. Supports filtering by NLP theme, sentiment, and source rank.
/authorsSearches for articles written by a specified author or set of authors. Supports the same filtering options as article search.
/search_by_linkRetrieves articles by their URL or NewsCatcher article ID. Use this endpoint to look up specific articles when you already know their links or identifiers.
/sourcesReturns a list of news sources indexed by NewsCatcher. Supports filtering by language, country, domain type, news category, and SEO rank.
/aggregation_countReturns article counts aggregated by day, hour, or month for a given query. Use this endpoint to analyze publication volume trends over time.
/subscriptionReturns details about your current subscription plan, including usage limits and entitlements.