> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Search news (JSON body) > Ranked real-news articles for a request in plain words or with keywords, grouped into stories. **How it ranks.** Every article is scored on relevance to the request, the authority of its publisher, how many newsrooms cover its story and how fresh it is. `effort` decides how much further work goes into the order: `low` stops there, `medium` adds a cross-encoder rerank of the top stories, `high` adds an LLM judgement of them and merges stories that report the same event. Articles in every language are searched through their English translation, unless every language you ask for is not English (then the original language is searched). **Filters.** `languages`, `countries`, `sources` and `min_newsrooms` narrow the search, `not_languages`, `not_countries` and `not_sources` leave articles out; `search_window` sets how far back to search, on the publication date (on the crawl date with `sort_by=crawled_at`): a number and a unit such as `15m`, `2h`, `1d`, `15 minutes`, `2 hours` or `1 day` (7 days by default, up to your plan's history). `collapse` decides what happens to several articles of one story. `sort_by` is `relevancy` (default), `published_at` or `crawled_at` (newest first; it covers the best matches of `q`, not every article of the window). An upper-case `NOT` in `q` drops the articles that mention the term in their headline, description or summary. **Credits.** A successful search (`200`) costs 1, 5 or 10 NCC for `low`, `medium` or `high` effort, also when it finds nothing. A refused or failed request is not charged. Your balance and limits are in `GET /subscription`. **Two ways to call it.** `GET /search` with the parameters in the query string, or `POST /search` with the same parameters as a JSON body. In both, `sources`, `languages`, `countries`, their `not_` versions and `include` take a comma-separated string; in the JSON body they can also be arrays. ## OpenAPI ````yaml /api-reference/news-api/openapi.json post /search openapi: 3.1.0 info: title: NewsCatcher News API summary: Ranked, story-aware news search. description: >- Search the news NewsCatcher has crawled in the last **30 days**, in every language: ranked by relevance, source authority and freshness, and grouped into **stories** (the articles that report the same event), with a one-line summary of each article. ## Authentication Send your API key in the `x-api-key` header of every request. Keys are created in the NewsCatcher platform. A missing or invalid key is answered with `401`. ## Endpoints | Endpoint | What it does | Charged | |---|---|---| | `GET` or `POST /search` | Ranked articles for a request in plain words or with keywords. | Yes, by effort | | `GET /stories/{story_id}` | Every article of one story. | Yes, 1 NCC per successful request | | `GET /subscription` | Your plan, limits and credit balance. | No | ## Effort and credits `effort` sets how much work goes into the ranking. A search is charged in **NCC** credits, by the effort you ask for, and only when it succeeds (`200`). | Effort | What it does | Credits | |---|---|---| | `low` | Ranks by relevance, authority, coverage and freshness. Fastest. | 1 | | `medium` (default) | Adds a cross-encoder rerank of the top stories. | 5 | | `high` | Adds an LLM judgement of the top stories and merges the stories that report the same event. Slowest, best quality. | 10 | A search that finds nothing is still charged. A request that is refused or fails (`401`, `402`, `403`, `422`, `429`, `500`, `503`) is never charged. ## Query `q` is a request in plain words or keywords, in any language, up to 500 characters. Put an upper-case `NOT` before a term to drop the articles that mention it in their headline, description or summary (`Apple NOT iPhone`). `languages`, `countries` and `sources` narrow the search; the time window is the last 7 days unless you set `search_window` (for example `15m`, `2h`, `1d`). ## Limits Your plan sets the requests per second (per effort level and in all), an optional daily limit, the most results per request (`limit`) and how far back you can search. `GET /subscription` returns all of them. Over a limit you get `429` with a `Retry-After` header. A `search_window` longer than your plan's history is cut to it and the response says `window.clamped`. ## Errors Every error has the same body: `message` (what went wrong), `status_code` and `status` (a short label). Use the HTTP status to decide what to do: | Status | Meaning | Retry the same request? | |---|---|---| | `401` | The API key is missing or invalid. | No | | `402` | Your credit balance does not cover the search. | After topping up | | `403` | The plan does not include what you asked for (a larger `limit`, an Enterprise field) or the key may not use this API. | No | | `404` | Unknown story. | No | | `422` | A parameter is missing, invalid or unknown, or the body is not valid JSON. | No, fix it first | | `429` | A rate limit of your plan. | Yes, after `Retry-After` seconds | | `500` | Something failed on our side. | Yes, and tell us the `Correlation-ID` | | `503` | A part of the service is temporarily unavailable. | Yes, after a short wait | Every response carries a `Correlation-ID` header (quote it to support) and an `X-Process-Time` header. ## Enterprise fields `include` adds heavy fields to every result (`description`, `entities`, `sentiment`, `themes`, `translation`, `embedding`). They are part of the Enterprise plans; other plans get `403` with `enterprise_field`. termsOfService: https://newscatcherapi.com/terms-of-service contact: name: NewsCatcher Support url: https://newscatcherapi.com/ email: support@newscatcherapi.com version: 1.0.0 servers: - url: https://api.newscatcherapi.com/news-api security: [] tags: - name: Search description: >- Search the news and read every article of a story. The articles are real news, ranked and grouped into stories. externalDocs: description: Search guide url: https://docs.newscatcherapi.com/ - name: Subscription description: Your plan, its limits and your credit balance. externalDocs: description: Plans and limits url: https://docs.newscatcherapi.com/ externalDocs: description: NewsCatcher documentation url: https://docs.newscatcherapi.com paths: /search: post: tags: - Search summary: Search news (JSON body) description: >- Ranked real-news articles for a request in plain words or with keywords, grouped into stories. **How it ranks.** Every article is scored on relevance to the request, the authority of its publisher, how many newsrooms cover its story and how fresh it is. `effort` decides how much further work goes into the order: `low` stops there, `medium` adds a cross-encoder rerank of the top stories, `high` adds an LLM judgement of them and merges stories that report the same event. Articles in every language are searched through their English translation, unless every language you ask for is not English (then the original language is searched). **Filters.** `languages`, `countries`, `sources` and `min_newsrooms` narrow the search, `not_languages`, `not_countries` and `not_sources` leave articles out; `search_window` sets how far back to search, on the publication date (on the crawl date with `sort_by=crawled_at`): a number and a unit such as `15m`, `2h`, `1d`, `15 minutes`, `2 hours` or `1 day` (7 days by default, up to your plan's history). `collapse` decides what happens to several articles of one story. `sort_by` is `relevancy` (default), `published_at` or `crawled_at` (newest first; it covers the best matches of `q`, not every article of the window). An upper-case `NOT` in `q` drops the articles that mention the term in their headline, description or summary. **Credits.** A successful search (`200`) costs 1, 5 or 10 NCC for `low`, `medium` or `high` effort, also when it finds nothing. A refused or failed request is not charged. Your balance and limits are in `GET /subscription`. **Two ways to call it.** `GET /search` with the parameters in the query string, or `POST /search` with the same parameters as a JSON body. In both, `sources`, `languages`, `countries`, their `not_` versions and `include` take a comma-separated string; in the JSON body they can also be arrays. operationId: newsSearchPost requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewsSearchRequest' examples: plain_words: summary: A request in plain words value: q: What is happening with the Florida hurricane recovery? effort: medium limit: 20 keywords_not: summary: Keywords with NOT, one language and country, last 3 days value: q: Tesla recall NOT Cybertruck effort: low limit: 10 languages: - en countries: - US search_window: 3d high_effort: summary: >- High effort, publishers and stories carried by 3 newsrooms or more value: q: central bank interest rates effort: high limit: 50 sources: - reuters.com - bloomberg.com min_newsrooms: 3 collapse: story enterprise: summary: With Enterprise fields value: q: OpenAI funding round include: - entities - sentiment - themes responses: '200': description: >- The articles, best first. `count` is 0 and `results` empty when nothing matched. content: application/json: schema: $ref: '#/components/schemas/NewsSearchResponse' examples: results: summary: A search with results value: query: hurricane recovery florida effort: medium took_ms: 3664 window: search_window: 7d hours: 168 from: '2026-10-21T14:12:35.408254+00:00' to: '2026-10-28T14:12:35.408254+00:00' count: 1 results: - id: 876a97d2bc58f3c2437ad7b03a06ebfe title: >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved language: en url: >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved source: domain: fox10tv.com name: FOX10News published_at: '2026-10-28T01:05:37+00:00' crawled_at: '2026-10-28T01:06:57+00:00' content_type: news_report story: id: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 newsrooms: 40 score: 36.1871 country: US snippet: >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery… summary: >- Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds. nothing_found: summary: Nothing matched (still charged) value: query: qwxz plorbt vrrnk effort: low took_ms: 884 window: search_window: 7d hours: 168 from: '2026-10-21T14:12:35.408254+00:00' to: '2026-10-28T14:12:35.408254+00:00' count: 0 results: [] enterprise_fields: summary: include=entities,sentiment,themes,description (Enterprise) value: query: hurricane recovery florida NOT insurance effort: high took_ms: 9786 window: search_window: 7d hours: 168 from: '2026-10-21T14:12:35.408254+00:00' to: '2026-10-28T14:12:35.408254+00:00' clamped: true count: 1 results: - id: 876a97d2bc58f3c2437ad7b03a06ebfe title: >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved language: en url: >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved source: domain: fox10tv.com name: FOX10News published_at: '2026-10-28T01:05:37+00:00' crawled_at: '2026-10-28T01:06:57+00:00' content_type: news_report story: id: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 newsrooms: 40 score: 36.1871 country: US snippet: >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery… summary: >- Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds. description: >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery efforts. entities: ner_PER: - Donald J. Trump ner_LOC: - Florida ner_MISC: - Hurricane Isaias sentiment: title: -0.1 content: 0.05 themes: - Weather - Politics - Disasters excluded: - insurance headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '401': description: The `x-api-key` header is missing, or the key is not valid. content: application/json: examples: missing_key: summary: Missing key value: message: >- The 'x-api-key' header is missing. Please provide your API key. status_code: 401 status: Unauthorized invalid_key: summary: Invalid key value: message: >- The 'x-api-key' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '402': description: >- Your credit balance does not cover the price of the search. Nothing was searched and nothing was charged. content: application/json: examples: insufficient_credits: summary: Insufficient credits value: message: >- Insufficient credits: a medium-effort search costs 5 NCC but your balance is 2 NCC. Please top up your credits. status_code: 402 status: Payment required schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '403': description: >- The request asks for more than your plan includes, or the key may not use the News API. content: application/json: examples: limit_above_plan: summary: Limit above plan value: message: >- Your plan allows up to 50 results per request, but you requested limit=51. status_code: 403 status: Forbidden enterprise_field: summary: Enterprise field value: message: >- enterprise_field: embedding is not included in your plan. Please upgrade to Enterprise. status_code: 403 status: Forbidden key_not_allowed: summary: Key not allowed value: message: >- This API key is not allowed to use the News API. Please check your account and organization access. status_code: 403 status: Forbidden other_product_key: summary: Other product key value: message: >- This API key belongs to another NewsCatcher product and cannot be used with the News API. Please use an API key from the NewsCatcher platform. status_code: 403 status: Forbidden schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '422': description: >- A parameter is missing, has the wrong type or an invalid value, is not a parameter of this endpoint, or the body is not valid JSON. The message names the parameter. Nothing was searched and nothing was charged. content: application/json: examples: invalid_value: summary: Invalid value value: message: The 'limit' parameter must be between 1 and 100. status_code: 422 status: Validation error missing_query: summary: Missing query value: message: '''q'' field required' status_code: 422 status: Validation error unknown_parameter: summary: Unknown parameter value: message: >- Invalid Parameter: 'mode'. Allowed parameters: q, effort, limit, collapse, sort_by, search_window, sources, languages, countries, not_sources, not_languages, not_countries, min_newsrooms, content_type, include. status_code: 422 status: Validation error invalid_country: summary: Invalid country value: message: >- Invalid country code(s): XX. Country codes must be valid ISO 3166-1 alpha-2 codes. status_code: 422 status: Validation error invalid_json: summary: Invalid json value: message: >- Invalid JSON format in request body. Please check your JSON syntax. status_code: 422 status: Validation error schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '429': description: >- You are over a rate limit of your plan: requests per second (per effort level, and in all) or requests per day. Wait for `Retry-After` seconds and send the request again; a refused request is not charged. headers: Retry-After: description: >- Seconds to wait before sending the request again: until the next second for the per-second limits, until 00:00 UTC for the daily limit. schema: type: integer minimum: 1 examples: - 1 Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' content: application/json: examples: per_second: summary: Per second value: message: >- Rate limit reached: your plan allows 1 requests per second for your organization. Please slow down and retry. status_code: 429 status: Too many requests per_day: summary: Per day value: message: >- Daily request limit reached: your plan allows 500 requests per day. The count restarts at 00:00 UTC. status_code: 429 status: Too many requests schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- Something failed on our side. Quote the `Correlation-ID` response header when you contact support. A failed request is not charged. content: application/json: examples: internal_error: summary: Internal error value: message: Internal server error occurred. Please contact support. status_code: 500 status: Internal error occurred schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' '503': description: >- A part of the service is temporarily unavailable. Send the same request again after a short wait; it was not charged. content: application/json: examples: limits_unavailable: summary: Limits unavailable value: message: >- Request limits are temporarily unavailable. Please retry shortly. status_code: 503 status: Service unavailable search_unavailable: summary: Search unavailable value: message: The news search backend is not available. status_code: 503 status: Service unavailable schema: $ref: '#/components/schemas/ErrorResponse' headers: Correlation-ID: $ref: '#/components/headers/Correlation-ID' X-Process-Time: $ref: '#/components/headers/X-Process-Time' security: - ApiKeyAuth: [] components: schemas: NewsSearchRequest: properties: q: type: string maxLength: 500 minLength: 1 description: >- What to look for: keywords with AND/OR/NOT or a plain-language question, in any language. An upper-case `NOT` (`Apple NOT iPhone`, `NOT "model y"`) drops the articles whose headline, description or summary mention the term. examples: - Tesla recall NOT Cybertruck effort: type: string enum: - low - medium - high description: >- How much work goes into the ranking, and the price: `low` ranks by relevance, authority, coverage and freshness (1 NCC); `medium` adds a cross-encoder rerank of the top stories (5 NCC); `high` adds an LLM rerank and merges stories about the same event (10 NCC). Charged only when the search succeeds. default: medium examples: - medium limit: type: integer maximum: 100 minimum: 1 description: >- Number of articles to return (1 to 100; a plan may allow fewer, e.g. 50 on Free: the request is refused with 403 above it). default: 20 examples: - 20 collapse: type: string enum: - diverse - story - duplicates description: >- `diverse` (default) discounts repeated articles of one story, `story` keeps one article per story, `duplicates` keeps every article (copies of one article are always one result). default: diverse examples: - diverse sort_by: type: string enum: - relevancy - published_at - crawled_at description: >- The order of the results: `relevancy` (default) best match first; `published_at` newest publication first; `crawled_at` newest crawl first. A date order covers the best matches of `q` (at least 100, or 5 times `limit`), not every article of the window, and `collapse=diverse` then keeps every article, as `duplicates` does. A publication date later than the crawl date counts as the crawl date. default: relevancy examples: - relevancy search_window: type: string pattern: ^\s*\d+(\.\d+)?\s*[a-zA-Z]+\s*$ description: >- How far back to search, counted from now and measured on the publication date: a number and a unit, for example `15m`, `2h`, `1d`, `15 minutes`, `2 hours`, `1 day` or `1w`. From 1 minute up to your plan's history (30 days on the free plan; a longer request is cut to it and the response says `window.clamped`). Default: `7d`. examples: - 7d - 2h - 15m - 1 day - 2 hours - 15 minutes sources: anyOf: - type: string description: Comma-separated values. examples: - reuters.com,bbc.co.uk - items: type: string description: Domain of a publisher, e.g. `reuters.com`. type: array maxItems: 100 examples: - - reuters.com - bbc.co.uk description: >- Only search these publishers: domains, comma-separated or as an array (at most 100). Matches any copy of an article. The result then shows the requested domain: its name, and a link of that domain (with several matching domains on one article, the first of them in the article's order). languages: anyOf: - type: string description: Comma-separated values. examples: - en,de - items: type: string pattern: ^[a-zA-Z]{2}$ description: >- ISO 639-1 language code; Chinese is `cn` (simplified) or `tw` (traditional), `zh` means `cn`. type: array maxItems: 100 examples: - - en - de description: >- Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is searched as `cn`. countries: anyOf: - type: string description: Comma-separated values. examples: - US,GB - items: type: string pattern: ^[a-zA-Z]{2}$ description: ISO 3166-1 alpha-2 country code. type: array maxItems: 100 examples: - - US - GB description: >- Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). not_sources: anyOf: - type: string description: Comma-separated values. examples: - reuters.com,bbc.co.uk - items: type: string description: Domain of a publisher, e.g. `reuters.com`. type: array maxItems: 100 examples: - - reuters.com - bbc.co.uk description: >- Leave out these publishers: domains, comma-separated or as an array (at most 100). An article is dropped when any of its copies comes from one of them. not_languages: anyOf: - type: string description: Comma-separated values. examples: - en,de - items: type: string pattern: ^[a-zA-Z]{2}$ description: >- ISO 639-1 language code; Chinese is `cn` (simplified) or `tw` (traditional), `zh` means `cn`. type: array maxItems: 100 examples: - - en - de description: >- Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is excluded as `cn`. not_countries: anyOf: - type: string description: Comma-separated values. examples: - US,GB - items: type: string pattern: ^[a-zA-Z]{2}$ description: ISO 3166-1 alpha-2 country code. type: array maxItems: 100 examples: - - US - GB description: >- Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). min_newsrooms: type: integer maximum: 1000 minimum: 0 description: Only stories carried by at least this many newsrooms. default: 0 examples: - 3 content_type: type: string enum: - news - all description: >- `news` (default) keeps real news articles only; `all` returns every article, whatever its type. default: news examples: - news include: anyOf: - type: string description: Comma-separated values. examples: - entities,sentiment - items: type: string enum: - description - entities - sentiment - themes - translation - embedding type: array maxItems: 100 examples: - - entities - sentiment description: >- Heavy fields to add to every result, comma-separated or as an array: description, entities, sentiment, themes, translation, embedding. Enterprise accounts only (403 `enterprise_field` otherwise). type: object required: - q title: NewsSearchRequest description: >- What to search for and how. The same parameters are accepted in the query string of `GET /search` and in the JSON body of `POST /search`. NewsSearchResponse: properties: query: type: string description: The query as received (control characters replaced, ends trimmed). examples: - hurricane recovery florida effort: type: string enum: - low - medium - high description: 'The effort level that ran: `low`, `medium` or `high`.' examples: - medium sort_by: anyOf: - type: string - type: 'null' description: >- The order of the results: `relevancy` (best match first), `published_at` or `crawled_at` (newest first). examples: - relevancy took_ms: type: integer minimum: 0 description: Time the search took on our side, in milliseconds. examples: - 3664 window: $ref: '#/components/schemas/NewsWindow' description: >- The time window that was searched: `search_window` back from `to`, which is when the search ran. count: type: integer minimum: 0 description: Number of results returned (at most `limit`). examples: - 1 results: items: $ref: '#/components/schemas/NewsResult' type: array description: The articles, in the order of `sort_by`. excluded: anyOf: - items: type: string type: array - type: 'null' description: >- The terms of the `NOT` clauses of `q`: articles whose headline, description or summary mention one are left out. Absent when `q` has no `NOT`. examples: - - iPhone type: object required: - query - effort - took_ms - window - count - results title: NewsSearchResponse description: The articles that match a search, with the window that was searched. examples: - count: 1 effort: medium query: hurricane recovery florida results: - content_type: news_report country: US crawled_at: '2026-10-28T01:06:57+00:00' id: 876a97d2bc58f3c2437ad7b03a06ebfe language: en published_at: '2026-10-28T01:05:37+00:00' score: 36.1871 snippet: >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery… source: domain: fox10tv.com name: FOX10News story: id: 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 newsrooms: 40 summary: >- Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds. title: >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved url: >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved took_ms: 3664 window: from: '2026-10-21T14:12:35.408254+00:00' hours: 168 search_window: 7d to: '2026-10-28T14:12:35.408254+00:00' ErrorResponse: properties: message: type: string description: >- What went wrong and, where it helps, what to do about it. Meant to be read by a person; do not parse it. examples: - The 'limit' parameter must be between 1 and 100. status_code: type: integer description: The HTTP status code of the response, repeated. examples: - 422 status: type: string enum: - Bad request - Unauthorized - Payment required - Forbidden - Not found - Method not allowed - Payload too large - Validation error - Too many requests - Internal error occurred - Service unavailable description: Short label of the status code. examples: - Validation error type: object required: - message - status_code - status title: Error description: The body of every error response. examples: - message: The 'limit' parameter must be between 1 and 100. status: Validation error status_code: 422 NewsWindow: properties: search_window: type: string description: >- The length of the window as the `search_window` that asks for it (`7d`, `2h`, `15m`): the one you sent, or your plan's limit when it cut it, or `7d` by default. examples: - 7d hours: type: number exclusiveMinimum: 0 description: >- The same length in hours (a fraction for minutes), counted back from `to`. examples: - 168 from: type: string format: date-time description: >- Start of the window (UTC, ISO 8601): `to` minus the length of the window. examples: - '2026-10-21T14:12:35.408254+00:00' to: type: string format: date-time description: 'End of the window: the moment the search ran (UTC, ISO 8601).' examples: - '2026-10-28T14:12:35.408254+00:00' clamped: anyOf: - type: boolean - type: 'null' description: >- True when the requested window was longer than your plan allows and was cut to it. Absent otherwise. examples: - true type: object required: - search_window - hours - from - to title: NewsWindow description: The time window that was searched. NewsResult: properties: id: type: string description: Article id. examples: - 876a97d2bc58f3c2437ad7b03a06ebfe title: type: string description: Headline as published. examples: - >- Major disaster declared in Florida following Hurricane Isaias; federal aid approved title_en: anyOf: - type: string - type: 'null' description: English translation of the headline (non-English articles only). examples: - 'Elections in Argentina: what is at stake' language: anyOf: - type: string - type: 'null' description: >- Language of the article, an ISO 639-1 code (Chinese is `cn` for simplified, `tw` for traditional). examples: - en url: type: string description: Link to the article. default: '' examples: - >- https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved source: $ref: '#/components/schemas/NewsSource' description: The publisher. published_at: anyOf: - type: string format: date-time - type: 'null' description: When the article was published (UTC, ISO 8601). examples: - '2026-10-28T01:05:37+00:00' crawled_at: anyOf: - type: string format: date-time - type: 'null' description: When NewsCatcher crawled the article (UTC, ISO 8601). examples: - '2026-10-28T01:06:57+00:00' content_type: type: string description: Type of content the article was classified as. default: news examples: - news_report story: $ref: '#/components/schemas/NewsStory' description: The story the article belongs to. score: type: number description: >- Ranking score; only the order of the results is meaningful, not the value. examples: - 36.1871 country: anyOf: - type: string - type: 'null' description: Country of the publisher, an ISO 3166-1 alpha-2 code. examples: - US snippet: anyOf: - type: string - type: 'null' description: >- Start of the publisher's description (up to your plan's snippet length, 200 characters on the free plan). examples: - >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery… summary: anyOf: - type: string - type: 'null' description: >- One-line summary in the article's language. Absent when the article has none. examples: - >- Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds. summary_en: anyOf: - type: string - type: 'null' description: >- One-line summary in English (non-English articles). Absent when the article has none. examples: - Argentina votes on Sunday in a closely watched midterm election. description: anyOf: - type: string - type: 'null' description: >- Full description from the publisher (`include=description`; Enterprise). examples: - >- President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday. entities: anyOf: - $ref: '#/components/schemas/NewsEntities' - type: 'null' description: Named entities (`include=entities`; Enterprise). sentiment: anyOf: - $ref: '#/components/schemas/NewsSentiment' - type: 'null' description: Sentiment scores (`include=sentiment`; Enterprise). themes: anyOf: - items: type: string type: array - type: 'null' description: Themes of the article (`include=themes`; Enterprise). examples: - - Finance - Economics - Business translation: anyOf: - $ref: '#/components/schemas/NewsTranslation' - type: 'null' description: >- English translation of the article (`include=translation`; Enterprise). embedding: anyOf: - items: type: number type: array - type: 'null' description: >- Dense vector of the article, 1,024 values each rounded to 4 decimal places (`include=embedding`; Enterprise). examples: - - 0.0123 - -0.0456 - 0.0789 type: object required: - id - title - source - story - score title: NewsResult description: One ranked article. NewsSource: properties: domain: type: string description: Domain of the publisher, without `www.`. default: '' examples: - reuters.com name: type: string description: Name of the publisher. default: '' examples: - Reuters type: object title: NewsSource description: The publisher of a result. NewsStory: properties: id: anyOf: - type: string - type: 'null' description: >- Story id; pass it to `GET /stories/{story_id}` to list every article of the story. examples: - 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 newsrooms: type: integer description: Number of newsrooms (distinct publishers) that cover the story. default: 1 examples: - 40 type: object title: NewsStory description: >- The story (a group of articles about the same event) a result belongs to. NewsEntities: properties: ner_PER: anyOf: - items: type: string type: array - type: 'null' description: People. examples: - - Aurangzeb - Muhammad Aurangzeb ner_ORG: anyOf: - items: type: string type: array - type: 'null' description: Organizations. examples: - - State Bank of Pakistan ner_LOC: anyOf: - items: type: string type: array - type: 'null' description: Locations. examples: - - Pakistan - Islamabad ner_MISC: anyOf: - items: type: string type: array - type: 'null' description: Other named entities (events, products, laws, …). examples: - - National Private Equity Framework translation_ner_PER: anyOf: - items: type: string type: array - type: 'null' description: People found in the English translation (non-English articles). examples: - - Nikola Grbić translation_ner_ORG: anyOf: - items: type: string type: array - type: 'null' description: >- Organizations found in the English translation (non-English articles). examples: - - WTA translation_ner_LOC: anyOf: - items: type: string type: array - type: 'null' description: Locations found in the English translation (non-English articles). examples: - - Wuhan translation_ner_MISC: anyOf: - items: type: string type: array - type: 'null' description: >- Other named entities found in the English translation (non-English articles). examples: - - Nations League type: object title: NewsEntities description: >- Named entities found in the article (`include=entities`; Enterprise). Each list holds the distinct names, in the order found; empty lists are left out. NewsSentiment: properties: title: anyOf: - type: number - type: 'null' description: Sentiment of the headline. examples: - -0.2 content: anyOf: - type: number - type: 'null' description: Sentiment of the article. examples: - 0.1 type: object title: NewsSentiment description: >- Sentiment of the article (`include=sentiment`; Enterprise): from -1 (very negative) through 0 (neutral) to 1 (very positive). NewsTranslation: properties: title: anyOf: - type: string - type: 'null' description: English headline. examples: - He searched for the right word and found it. summary: anyOf: - type: string - type: 'null' description: English summary of the article. examples: - >- Maja Chwalińska won the WTA 1000 tournament in Wuhan and reached the final of Roland Garros. type: object title: NewsTranslation description: >- English translation of a non-English article (`include=translation`; Enterprise). Parts that do not exist are left out. headers: Correlation-ID: description: >- Id of this request. Quote it when you contact support: it finds the request in our logs. schema: type: string format: uuid examples: - 6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11 X-Process-Time: description: Seconds the API spent on the request. schema: type: string examples: - '0.1884448528289795' securitySchemes: ApiKeyAuth: type: apiKey description: >- Your NewsCatcher API key, created in the NewsCatcher platform. Send it in the `x-api-key` header of every request. in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.