> ## 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. # Get breaking news > Retrieves breaking news articles and sorts them based on specified criteria. ## OpenAPI ````yaml news-api-v3 post /api/breaking_news openapi: 3.1.0 info: title: NewsCatcher News API description: > NewsCatcher News API provides programmatic access to a continuously updated global news index. It includes endpoints for article search, latest headlines, breaking news, author search, aggregation counts, and source discovery. ## Key features - **Full-text search**: Query articles by keyword, phrase, language, country, source, publication date, sentiment, and more using Boolean operators and advanced filters. - **NLP enrichment**: Articles include theme classification, sentiment scores, and named entity recognition (people, organizations, locations). - **Article clustering**: Group similar articles into clusters to reduce noise and surface unique stories. - **Deduplication**: Exclude duplicate articles from results to keep datasets clean and relevant. - **Source intelligence**: Discover and filter news sources by domain, type, rank, and geographic origin. For documentation, integration guides, and SDKs, visit the [developer portal](https://wwwnewscatcherapi.com/docs). termsOfService: https://newscatcherapi.com/terms-of-service contact: name: Maksym Sugonyaka email: maksym@newscatcherapi.com version: 3.24.0 servers: - url: https://v3-api.newscatcherapi.com description: News API production server security: - ApiKeyAuth: [] tags: - name: Search description: Operations to search for articles. externalDocs: description: Search for articles by keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search/search-articles-get - name: LatestHeadlines description: Operations to retrieve latest headlines. externalDocs: description: >- Retrieve the latest headlines since a specified date, with filtering options. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/latest-headlines/retrieve-latest-headlines-get - name: BreakingNews description: Operations to retrieve breaking news articles. externalDocs: description: Retrieve breaking news articles. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/breaking-news/breaking-news-get - name: Authors description: Operations to search by author. externalDocs: description: Search for articles by author. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/authors/search-articles-by-author-get - name: SearchByLink description: Operations to search by link or ID. externalDocs: description: Search for articles by link or ID. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search-by-link/search-articles-by-links-or-ids-get - name: Sources description: Operations to retrieve news sources. externalDocs: description: >- Retrieve the list of available sources, filtered by language and country. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/sources/retrieve-sources-get - name: AggregationCount description: Operations to aggregate news counts. externalDocs: description: >- Aggregate news counts based on specified criteria such as keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/aggregation-count/get-aggregation-count-by-interval-get - name: Subscription description: Operations to get subscription info. externalDocs: description: Retrieve information about your subscription plan. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/subscription/retrieve-subscription-plan-information-get externalDocs: description: Find out more about NewsCatcher News API url: https://www.newscatcherapi.com/docs paths: /api/breaking_news: post: tags: - BreakingNews summary: Get breaking news description: >- Retrieves breaking news articles and sorts them based on specified criteria. operationId: breakingNewsPost requestBody: $ref: '#/components/requestBodies/BreakingNewsRequestBody' responses: '200': $ref: '#/components/responses/BreakingNewsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '408': $ref: '#/components/responses/RequestTimeoutError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' components: requestBodies: BreakingNewsRequestBody: description: >- Request body for retrieving breaking news articles with sorting and filtering options. required: true content: application/json: schema: type: object properties: sort_by: $ref: '#/components/schemas/SortBy' ranked_only: $ref: '#/components/schemas/RankedOnly' from_rank: $ref: '#/components/schemas/FromRank' to_rank: $ref: '#/components/schemas/ToRank' page: $ref: '#/components/schemas/Page' page_size: $ref: '#/components/schemas/PageSize' top_n_articles: $ref: '#/components/schemas/TopNArticles' include_translation_fields: $ref: '#/components/schemas/IncludeTranslationFields' include_nlp_data: $ref: '#/components/schemas/IncludeNlpData' has_nlp: $ref: '#/components/schemas/HasNlp' theme: $ref: '#/components/schemas/Theme' not_theme: $ref: '#/components/schemas/NotTheme' ORG_entity_name: $ref: '#/components/schemas/OrgEntityName' PER_entity_name: $ref: '#/components/schemas/PerEntityName' LOC_entity_name: $ref: '#/components/schemas/LocEntityName' MISC_entity_name: $ref: '#/components/schemas/MiscEntityName' title_sentiment_min: $ref: '#/components/schemas/TitleSentimentMin' title_sentiment_max: $ref: '#/components/schemas/TitleSentimentMax' content_sentiment_min: $ref: '#/components/schemas/ContentSentimentMin' content_sentiment_max: $ref: '#/components/schemas/ContentSentimentMax' example: sort_by: relevancy ranked_only: true top_n_articles: 1 responses: BreakingNewsResponse: description: >- A successful response containing breaking news articles with additional breaking news event information. content: application/json: schema: $ref: '#/components/schemas/BreakingNewsResponseDto' BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid JSON in request body status_code: 400 status: Bad request UnauthorizedError: description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The 'x-api-token' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized ForbiddenError: description: Forbidden - Server refuses action content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Your plan request date range cannot be greater than 400 days status_code: 403 status: Forbidden RequestTimeoutError: description: Request timeout content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Request timed out after 30 seconds status_code: 408 status: Request timeout ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid date format status_code: 422 status: Validation error RateLimitError: description: Too many requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Max API requests concurrency reached status_code: 429 status: Too many requests InternalServerError: description: Internal server error content: text/plain: schema: type: string example: Internal Server Error schemas: SortBy: type: string enum: - relevancy - date - rank default: relevancy description: | The sorting order of the results. Possible values are: - `relevancy`: The most relevant results first. - `date`: The most recently published results first. - `rank`: The results from the highest-ranked sources first. example: date RankedOnly: type: boolean default: true description: > If true, limits the search to sources ranked in the top 1 million online websites. If false, includes unranked sources which are assigned a rank of 999999. example: true FromRank: type: integer minimum: 1 maximum: 999999 default: 1 format: int32 description: > The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source. example: 100 ToRank: type: integer minimum: 1 maximum: 999999 default: 999999 format: int32 description: > The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source. example: 100 Page: type: integer minimum: 1 default: 1 description: > The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles. For details, see [Retrieve large datasets](https://www.newscatcherapi.com/docs/news-api/how-to/retrieve-more-than-10k-articles) example: 2 PageSize: type: integer minimum: 1 maximum: 1000 default: 100 description: | The number of articles to return per page. example: 50 TopNArticles: type: integer minimum: 1 maximum: 100 default: 1 description: > Controls the number of top articles to include for each breaking news event. **Important limitations**: - Maximum value is 100. - The product of `top_n_articles` x `page_size` must not exceed 1,000 (total articles limit). example: 5 IncludeTranslationFields: type: boolean default: false description: > If true, includes English translation fields in the response (`title_translated_en`, `content_translated_en`, and NLP translation fields). example: true IncludeNlpData: type: boolean default: false description: > If true, includes an NLP object for each article in the response. This object provides results of NLP analysis, including article theme, summary, sentiment, tags, and named entity recognition if available. **Note**: NLP data is only available for articles indexed from July 2023 onward. For articles indexed before July 2023, the `nlp` field is returned as an empty object `{}`. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: true HasNlp: type: boolean default: false description: > If true, filters results to include only articles that have NLP data. **Note**: NLP data is only available for articles indexed from July 2023 onward. Applying this filter to a date range that predates July 2023 returns zero results. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: true Theme: type: string example: Finance,Tech description: > Filters articles based on their general topic, as determined by NLP analysis. To select multiple themes, use a comma-separated string. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). Available options: `Business`, `Economics`, `Entertainment`, `Finance`, `Health`, `Politics`, `Science`, `Sports`, `Tech`, `Crime`, `Financial Crime`, `Lifestyle`, `Automotive`, `Travel`, `Weather`, `General`. NotTheme: type: string example: Crime,Sports description: > Inverse of the `theme` parameter. Excludes articles based on their general topic, as determined by NLP analysis. To exclude multiple themes, use a comma-separated string. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). OrgEntityName: type: string description: > Filters articles that mention specific organization names, as identified by NLP analysis. - To specify multiple organizations, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. - To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`). To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity). example: '"Apple Inc" OR Microsoft' PerEntityName: type: string description: > Filters articles that mention specific person names, as identified by NLP analysis. - To specify multiple names, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. - To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`). To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity). example: '"Elon Musk" OR "Jeff Bezos"' LocEntityName: type: string description: > Filters articles that mention specific location names, as identified by NLP analysis. - To specify multiple locations, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. - To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`). To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity). example: '"San Francisco" OR "New York City"' MiscEntityName: type: string description: > Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more. - To specify multiple entities, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. - To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`). To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity). example: AWS OR "Microsoft Azure" TitleSentimentMin: type: number format: float minimum: -1 maximum: 1 description: > Filters articles based on the minimum sentiment score of their titles. Range is `-1.0` to `1.0`, where: - Negative values indicate negative sentiment. - Positive values indicate positive sentiment. - Values close to 0 indicate neutral sentiment. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: -0.5 TitleSentimentMax: type: number format: float minimum: -1 maximum: 1 description: > Filters articles based on the maximum sentiment score of their titles. Range is `-1.0` to `1.0`, where: - Negative values indicate negative sentiment. - Positive values indicate positive sentiment. - Values close to 0 indicate neutral sentiment. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: 0.5 ContentSentimentMin: type: number format: float minimum: -1 maximum: 1 description: > Filters articles based on the minimum sentiment score of their content. Range is `-1.0` to `1.0`, where: - Negative values indicate negative sentiment. - Positive values indicate positive sentiment. - Values close to 0 indicate neutral sentiment. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: -0.5 ContentSentimentMax: type: number format: float minimum: -1 maximum: 1 description: > Filters articles based on the maximum sentiment score of their content. Range is `-1.0` to `1.0`, where: - Negative values indicate negative sentiment. - Positive values indicate positive sentiment. - Values close to 0 indicate neutral sentiment. To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features). example: 0.5 BreakingNewsResponseDto: title: Breaking News Response description: > The response model for the breaking news requests. Response field behavior: - Required fields are guaranteed to be present and non-null. - Optional fields may be `null` or `undefined` if the data point is not presented or couldn't be extracted during processing. - To access article properties in the `articles` response array, use array index notation. For example, `articles[n].title`, where `n` is the zero-based index of the article object (0, 1, 2, etc.). - The `nlp` property within the article object `articles[n].nlp` is only available with NLP-enabled subscription plans. allOf: - $ref: '#/components/schemas/BaseSearchResponseDto' - type: object properties: breaking_news_events: title: Breaking News Events description: >- A list of breaking news events, each containing relevant articles. type: array items: $ref: '#/components/schemas/BreakingNewsEventEntity' default: [] user_input: $ref: '#/components/schemas/UserInputDto' Error: type: object properties: message: type: string description: A detailed description of the error. status_code: type: integer description: The HTTP status code of the error. status: type: string description: A short description of the status code. required: - message - status_code - status BaseSearchResponseDto: title: Base Search Response description: The base response model containing common fields for search operations. required: - status - total_hits - page - total_pages - page_size type: object properties: status: title: Status description: The status of the response. type: string total_hits: title: Total Hits description: The total number of articles matching the search criteria. type: integer page: title: Page description: The current page number of the results. type: integer total_pages: title: Total Pages description: The total number of pages available for the given search criteria. type: integer page_size: title: Page Size description: The number of articles per page. type: integer BreakingNewsEventEntity: title: Breaking News Event Object description: > The data model representing a breaking news event with its associated articles. required: - event_id - articles_count - articles type: object properties: event_id: title: Event ID description: Unique identifier for the breaking news event/cluster. type: string articles_count: title: Articles Count description: Number of articles in this breaking news cluster. type: integer articles: title: Articles description: The articles associated with this breaking news event. type: array items: $ref: '#/components/schemas/BreakingNewsArticleEntity' default: [] UserInputDto: type: object description: The user input parameters for the request. additionalProperties: true BreakingNewsArticleEntity: title: Breaking News Article Object description: > The data model representing a single article in the `Breaking news` search results. required: - title - link - domain_url - full_domain_url - parent_url - rank - id - score type: object properties: title: title: Title description: The title of the article. type: string author: title: Author description: The primary author of the article. type: string authors: title: Authors description: A list of authors of the article. anyOf: - type: array items: type: string - type: string journalists: title: Journalists description: A list of journalists associated with the article. anyOf: - type: array items: type: string - type: string - type: 'null' published_date: title: Published Date description: The date the article was published. type: string published_date_precision: title: Published Date Precision description: The precision of the published date. type: string updated_date: title: Updated Date description: The date the article was last updated. type: - string - 'null' updated_date_precision: title: Updated Date Precision description: The precision of the updated date. type: - string - 'null' parse_date: title: Parse Date description: The date the article was parsed. type: - string - 'null' link: title: Link description: The URL link to the article. type: string domain_url: title: Domain URL description: The domain URL of the article. type: string full_domain_url: title: Full Domain URL description: The full domain URL of the article. type: string name_source: title: Name Source description: The name of the source where the article was published. type: string is_headline: title: Is Headline description: Indicates if the article is a headline. type: boolean paid_content: title: Paid Content description: >- Indicates whether the source labels the article as paywalled or requiring a subscription for full access. type: boolean parent_url: title: Parent URL description: The categorical URL of the article. type: string country: title: Country description: The country where the article was published. type: string rights: title: Rights description: The rights information for the article. type: string rank: title: Rank description: The rank of the article's source. type: integer media: title: Media description: The media associated with the article. type: string language: title: Language description: The language in which the article is written. type: string description: title: Description description: A brief description of the article. type: string content: title: Content description: The content of the article. type: string title_translated_en: type: - string - 'null' description: > English translation of the article title. Available when setting the `include_translation_fields` parameter to `true`. content_translated_en: type: - string - 'null' description: > English translation of the article content. Available when setting the `include_translation_fields` parameter to `true`. word_count: title: Word Count description: The word count of the article. type: integer default: 0 is_opinion: title: Is Opinion description: Indicates if the article is an opinion piece. type: boolean twitter_account: title: Twitter Account description: The Twitter account associated with the article. type: - string - 'null' all_links: title: All Links description: A list of all URLs mentioned in the article. anyOf: - type: array items: type: string - type: string default: [] all_domain_links: title: All Domain Links description: A list of all domain URLs mentioned in the article. anyOf: - type: array items: type: string - type: string default: [] nlp: $ref: '#/components/schemas/NlpDataEntity' id: title: ID description: The unique identifier for the article. type: string score: title: Score description: The relevance score of the article. type: number NlpDataEntity: type: object default: {} description: Natural Language Processing data for the article. properties: translation_summary: type: string description: | A brief AI-generated summary of the article's English translation. theme: type: string description: The themes or categories identified in the article. summary: type: string description: A brief AI-generated summary of the article content. sentiment: $ref: '#/components/schemas/SentimentScores' new_embedding: type: array items: type: number format: float description: > A dense 1024-dimensional vector representation of the article content, generated using the [multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large) model. Available for articles indexed before January 1, 2026. **Note**: The `new_embedding` field is only available in the `v3_nlp_embeddings` subscription plan. qwen_embedding: type: array items: type: number format: float description: > A dense 1024-dimensional vector representation of the article content, generated using the [Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding) model. Available for articles indexed from January 1, 2026 onward. Embeddings are computed from a combination of the article `title` and `content` fields. **Note**: The `qwen_embedding` field is only available in the `v3_nlp_embeddings` subscription plan. ner_PER: allOf: - $ref: '#/components/schemas/NamedEntityList' description: Named Entity Recognition for person entities (individuals' names). ner_ORG: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for organization entities (company names, institutions). ner_MISC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for miscellaneous entities (events, nationalities, products). ner_LOC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: >- Named Entity Recognition for location entities (cities, countries, geographic features). translation_ner_PER: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for person entities (individuals' names) extracted from the English translation of the article. translation_ner_ORG: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for organization entities (company names, institutions) extracted from the English translation of the article. translation_ner_MISC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for miscellaneous entities (events, nationalities, products) extracted from the English translation of the article. translation_ner_LOC: allOf: - $ref: '#/components/schemas/NamedEntityList' description: > Named Entity Recognition for location entities (cities, countries, geographic features) extracted from the English translation of the article. iptc_tags_name: type: array items: type: string description: > IPTC media topic taxonomy paths identified in the article content. Each path represents a hierarchical category following the IPTC standard. **Note**: The `iptc_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan. iptc_tags_id: type: array items: type: string description: > IPTC media topic numeric codes identified in the article content. These codes correspond to the standardized IPTC media topic taxonomy. **Note**: The `iptc_tags_id` field is only available in the `v3_nlp_iptc_tags` subscription plan. iab_tags_name: type: array items: type: string description: > IAB content taxonomy paths identified in the article content. Each path represents a hierarchical category following the IAB content standard. **Note**: The `iab_tags_name` field is only available in the `v3_nlp_iptc_tags` subscription plan. SentimentScores: type: object description: Sentiment scores for the article's title and content. properties: title: type: number format: float description: The sentiment score for the article title (-1.0 to 1.0). content: type: number format: float description: The sentiment score for the article content (-1.0 to 1.0). NamedEntityList: type: array description: A list of named entities identified in the article. items: type: object properties: entity_name: type: string description: The name of the entity identified in the article. count: type: integer description: The number of times this entity appears in the article. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token description: > API Key to authenticate requests. To access the API, include your API key in the `x-api-token` header. To obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly. ````