> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # API reference overview > Base URL, authentication, request format, and endpoints for News API. ## 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: ```http theme={null} x-api-token: YOUR_API_KEY ``` For implementation examples in all supported languages, see [Authentication](/news-api/api-reference/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. ```bash cURL theme={null} 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 }' ``` ```python Python theme={null} from newscatcher import NewscatcherApi client = NewscatcherApi(api_key="YOUR_API_KEY") response = client.search.post( q="renewable energy", lang="en", page_size=1, ) print(response.articles[0].title) ``` ```typescript TypeScript theme={null} import { NewscatcherApiClient } from "newscatcher-sdk"; const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" }); const response = await client.search.post({ q: "renewable energy", lang: "en", pageSize: 1, }); console.log(response.articles?.[0]?.title); ``` ```java Java theme={null} import com.newscatcher.api.NewscatcherApiClient; import com.newscatcher.api.resources.search.requests.PostSearchRequest; NewscatcherApiClient client = NewscatcherApiClient.builder() .apiKey("YOUR_API_KEY") .build(); var response = client.search().post( PostSearchRequest.builder() .q("renewable energy") .lang("en") .pageSize(1) .build() ); System.out.println(response.getArticles().get(0).getTitle()); ``` | | GET | POST | | ---------------- | --------------------------- | ---------------------------------------- | | Parameters | URL query string | JSON request body | | URL length limit | Limited (varies by client) | None | | Best for | Quick testing and debugging | Complex 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: ```json theme={null} { "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: | Parameter | Default | Maximum | | ----------- | ------- | ------------------------------------------------------------- | | `page` | `1` | No hard limit, but results cap at 10,000 articles per request | | `page_size` | `100` | `1000` | 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](/news-api/how-to/retrieve-more-than-10k-articles). ## 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](/news-api/api-reference/rate-limits). ## Errors All error responses use a consistent JSON envelope: ```json theme={null} { "message": "Invalid api key", "status_code": 401, "status": "Unauthorized" } ``` For the full list of status codes and resolution steps, see [Errors](/news-api/api-reference/errors). ## Endpoints News API provides the following endpoints. All endpoints support both `GET` and `POST` methods. | Endpoint | Description | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [/search](/news-api/api-reference/search) | Searches for articles by keyword, phrase, or Boolean query. Supports filtering by language, country, source, date range, sentiment, NLP tags, and more. | | [/latest\_headlines](/news-api/api-reference/latest-headlines) | Returns the most recent headlines published within a specified time window. Supports filtering by language, country, source, and NLP attributes. | | [/breaking\_news](/news-api/api-reference/breaking-news) | Returns actively breaking news events, each with a configurable number of top representative articles. Supports filtering by NLP theme, sentiment, and source rank. | | [/authors](/news-api/api-reference/authors) | Searches for articles written by a specified author or set of authors. Supports the same filtering options as article search. | | [/search\_by\_link](/news-api/api-reference/search-by-link) | Retrieves articles by their URL or NewsCatcher article ID. Use this endpoint to look up specific articles when you already know their links or identifiers. | | [/sources](/news-api/api-reference/sources) | Returns a list of news sources indexed by NewsCatcher. Supports filtering by language, country, domain type, news category, and SEO rank. | | [/aggregation\_count](/news-api/api-reference/aggregation-count) | Returns article counts aggregated by day, hour, or month for a given query. Use this endpoint to analyze publication volume trends over time. | | [/subscription](/news-api/api-reference/subscription) | Returns details about your current subscription plan, including usage limits and entitlements. |