--- title: "Get breaking news" method: POST path: "/api/breaking_news" tags: ["BreakingNews"] --- # Get breaking news `POST /api/breaking_news` ## Request - Base URL: `https://v3-api.newscatcherapi.com` (the document declares no server; this is the origin it was published from) - URL: `https://v3-api.newscatcherapi.com/api/breaking_news` - Auth: none declared. Required headers: `x-api-token` Returns articles flagged as breaking news within the last 24 hours, grouped into breaking news events: clusters of related articles covering the same story from different sources. Supports filtering by theme, named entities (organizations, people, locations, misc.), sentiment, and source rank. ## Headers - `x-api-token` string, required: Your NewsCatcher API key, used to authenticate this request. ## Request body - BreakingNewsRequest: Breaking news request DTO - `sort_by` string: Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first). - `ranked_only` union: When true, only returns articles from sources that have a known rank (excludes unranked sources). - string - boolean - `from_rank` union: Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999. - string - integer - `to_rank` union: Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999. - string - integer - `page` union: Page number of results to return, starting at 1. - string - integer - `page_size` union: Number of articles per page. Integer between 1 and 1000. - string - integer - `include_nlp_data` union: For NLP-enabled plans, controls whether the nlp object is included in the response for each article (excluded by default). Basic plan always includes nlp.theme regardless of this setting. - string - boolean - `has_nlp` boolean: When true, only returns articles that have NLP enrichment data. Requires an NLP plan. - `theme` string: Filter by article theme. One of: Business, Politics, Entertainment, Sports, Finance, Crime, Tech, General, Health, Economics, Science, Automotive, Weather, Travel, Lifestyle, Financial Crime. Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article (e.g. 'Tech AND Finance,Sports' matches Tech-and-Finance articles, or Sports articles). - `not_theme` string: Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match. - `ORG_entity_name` string: Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan. - `PER_entity_name` string: Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan. - `LOC_entity_name` string: Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan. - `MISC_entity_name` string: Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan. - `title_sentiment_min` number: Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan. - `title_sentiment_max` number: Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan. - `content_sentiment_min` number: Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan. - `content_sentiment_max` number: Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan. - `top_n_articles` union: Number of top articles to return per breaking news event. Integer between 1 and 100. The product of top_n_articles and page_size must not exceed 1000. - string - integer - `include_translation_fields` union: Includes machine-translated title/content fields (title_translated_en, content_translated_en) in the response for non-English articles. Automatically enabled if search_in includes a '_translated' field. - string - boolean - `robots_compliant` union: Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones. - string - boolean ## Response `200` Successful Response - BreakingNewsResponse: BreakingNewsResponse DTO class. - `status` string: Always 'ok' for a successful breaking news search. - `total_hits` integer, required: Total number of breaking news events matching the request, across all pages. - `page` integer, required: Current page number returned. - `total_pages` integer, required: Total number of pages available for this query, given page_size. - `page_size` integer, required: Number of breaking news events returned per page. - `breaking_news_events` object[], required: Breaking news events matching the request, each a cluster of related articles. - `user_input` object, required: Echo of the request parameters that produced this response. ## Other responses - `401`: Missing or invalid `x-api-token` header. - `403`: A supplied parameter isn't included in your subscription plan, or the requested date range exceeds your plan's allowed history window. Also returned to free tier (trial) keys whose trial has ended or whose included calls are used up. - `408`: Your query reached the search backend but did not finish within 30 seconds. Narrow the date range, lower page_size, or simplify the query. Note this covers only genuinely slow queries - if the backend could not be reached at all the response is 503, which is retryable as-is. - `422`: Request validation failed, e.g. an invalid parameter value or a missing required field. - `429`: Rate limit exceeded for your plan. - `499`: The HTTP status line is 499, but the response body's own `status_code` field reads 422 - a known quirk of this API's validation-error handling for cases not covered by the standard 422 path, not a documentation error. - `503`: The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged. --- [API](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api.md) - [All operations](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/llms.txt) - [OpenAPI document](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/revisions/a3950aefb3e5?raw)