{"openapi":"3.0.2","info":{"title":"NewsCatcher-V3 Production API","description":"<img src='https://uploads-ssl.webflow.com/6429857b17973b636c2195c5/646c6f1eb774ff2f2997bec5_newscatcher_.svg' width='286' height='35' /> <br>  <br>Visit our website  <a href='https://newscatcherapi.com'>https://newscatcherapi.com</a> <br> <p style=\"color: red\"><b><em><a href=\"https://docs.newscatcherapi.com/api-docs/endpoints-1\">Read our V3 Documentation</a></em></b></p> <br>","termsOfService":"https://newscatcherapi.com/terms-of-service","contact":{"name":"Maksym Sugonyaka","email":"maksym@newscatcherapi.com"},"version":"4.1.3"},"paths":{"/api/search":{"get":{"tags":["Search"],"summary":"Search articles","description":"Full-text search across the NewsCatcher News API index. Supports filtering by keyword, language, country, source, publication date, and dozens of other parameters; results can optionally be grouped into clusters of similar articles.","operationId":"searchGet","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q","description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},"description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},{"name":"search_in","in":"query","required":false,"schema":{"type":"string","default":"title_content","title":"Search In","description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated."},"description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated."},{"name":"predefined_sources","in":"query","required":false,"schema":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},{"name":"sources","in":"query","required":false,"schema":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"source_groups","in":"query","required":false,"schema":{"title":"Source Groups","description":"Restrict the search to the publisher domains of one or more curated source groups, given by slug (e.g. 'top_100_us_finance'). Call GET /api/source-groups for the available slugs. Combine multiple as a comma-separated string or array; their domains are merged. Behaves like `sources` once resolved, including suppressing `countries`."},"description":"Restrict the search to the publisher domains of one or more curated source groups, given by slug (e.g. 'top_100_us_finance'). Call GET /api/source-groups for the available slugs. Combine multiple as a comma-separated string or array; their domains are merged. Behaves like `sources` once resolved, including suppressing `countries`."},{"name":"not_sources","in":"query","required":false,"schema":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"lang","in":"query","required":false,"schema":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"not_lang","in":"query","required":false,"schema":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"countries","in":"query","required":false,"schema":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_countries","in":"query","required":false,"schema":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_author_name","in":"query","required":false,"schema":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"description":"Exclude articles written by any of the given author names."},{"name":"from_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},{"name":"to_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},{"name":"published_date_precision","in":"query","required":false,"schema":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone)."},{"name":"by_parse_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"default":false,"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},"description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"relevancy","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},"description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},{"name":"ranked_only","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},{"name":"from_rank","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"to_rank","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"is_headline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},{"name":"is_opinion","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"description":"Filter by whether the article is opinion/editorial content."},{"name":"is_paid_content","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},{"name":"parent_url","in":"query","required":false,"schema":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},{"name":"all_links","in":"query","required":false,"schema":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"description":"Filter for articles that link to any of the given URLs anywhere in their content."},{"name":"all_domain_links","in":"query","required":false,"schema":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"description":"Filter for articles that link to any of the given domains anywhere in their content."},{"name":"all_links_text","in":"query","required":false,"schema":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},{"name":"word_count_min","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},"description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},{"name":"word_count_max","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},"description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"clustering_variable","in":"query","required":false,"schema":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'."},{"name":"clustering_enabled","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},{"name":"clustering_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},"description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},{"name":"include_nlp_data","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Nlp Data","description":"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."},"description":"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."},{"name":"has_nlp","in":"query","required":false,"schema":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan."},{"name":"theme","in":"query","required":false,"schema":{"title":"Theme","description":"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).","type":"string"},"description":"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)."},{"name":"not_theme","in":"query","required":false,"schema":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match."},{"name":"ORG_entity_name","in":"query","required":false,"schema":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"PER_entity_name","in":"query","required":false,"schema":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"LOC_entity_name","in":"query","required":false,"schema":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"MISC_entity_name","in":"query","required":false,"schema":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"title_sentiment_min","in":"query","required":false,"schema":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"title_sentiment_max","in":"query","required":false,"schema":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_min","in":"query","required":false,"schema":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_max","in":"query","required":false,"schema":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"iptc_tags","in":"query","required":false,"schema":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},{"name":"not_iptc_tags","in":"query","required":false,"schema":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},{"name":"source_name","in":"query","required":false,"schema":{"title":"Source Name","description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},"description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},{"name":"iab_tags","in":"query","required":false,"schema":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},{"name":"not_iab_tags","in":"query","required":false,"schema":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},{"name":"exclude_duplicates","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Exclude Duplicates","description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."},"description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."},{"name":"additional_domain_info","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Additional Domain Info","description":"Includes extra domain-level information (e.g. traffic/audience data) for each article's source, where available."},"description":"Includes extra domain-level information (e.g. traffic/audience data) for each article's source, where available."},{"name":"is_news_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is News Domain","description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},"description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},{"name":"news_domain_type","in":"query","required":false,"schema":{"title":"News Domain Type","description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},"description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},{"name":"news_type","in":"query","required":false,"schema":{"title":"News Type","description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."},"description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."},{"name":"include_translation_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"description":"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."},{"name":"robots_compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchResponse"},{"$ref":"#/components/schemas/ClusteringSearchResponse"}],"title":"Response Searchget"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["Search"],"summary":"Search articles","description":"Full-text search across the NewsCatcher News API index. Supports filtering by keyword, language, country, source, publication date, and dozens of other parameters; results can optionally be grouped into clusters of similar articles.","operationId":"searchPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchResponse"},{"$ref":"#/components/schemas/ClusteringSearchResponse"}],"title":"Response Searchpost"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/latest_headlines":{"get":{"tags":["LatestHeadlines"],"summary":"Get latest headlines","description":"Returns the most recent articles ('headlines') published since a given lookback window, specified via the when parameter, up to now. Supports filtering by language, country, source, and dozens of other parameters; results can optionally be grouped into clusters of similar articles.","operationId":"latestHeadlinesGet","parameters":[{"name":"when","in":"query","required":false,"schema":{"type":"string","default":"7d","title":"When","description":"How far back to look for headlines, replacing from_/to_ for this endpoint. Format: '<N>d' for N days ago or '<N>h' for N hours ago (e.g. '7d', '24h'). Results run from this point up to now."},"description":"How far back to look for headlines, replacing from_/to_ for this endpoint. Format: '<N>d' for N days ago or '<N>h' for N hours ago (e.g. '7d', '24h'). Results run from this point up to now."},{"name":"by_parse_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"default":false,"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},"description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"relevancy","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},"description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},{"name":"lang","in":"query","required":false,"schema":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"not_lang","in":"query","required":false,"schema":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"countries","in":"query","required":false,"schema":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_countries","in":"query","required":false,"schema":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"sources","in":"query","required":false,"schema":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"predefined_sources","in":"query","required":false,"schema":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},{"name":"not_sources","in":"query","required":false,"schema":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"not_author_name","in":"query","required":false,"schema":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"description":"Exclude articles written by any of the given author names."},{"name":"ranked_only","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},{"name":"is_headline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},{"name":"is_opinion","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"description":"Filter by whether the article is opinion/editorial content."},{"name":"is_paid_content","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},{"name":"parent_url","in":"query","required":false,"schema":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},{"name":"all_links","in":"query","required":false,"schema":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"description":"Filter for articles that link to any of the given URLs anywhere in their content."},{"name":"all_domain_links","in":"query","required":false,"schema":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"description":"Filter for articles that link to any of the given domains anywhere in their content."},{"name":"all_links_text","in":"query","required":false,"schema":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},{"name":"word_count_min","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},"description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},{"name":"word_count_max","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},"description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"clustering_variable","in":"query","required":false,"schema":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'."},{"name":"clustering_enabled","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},{"name":"clustering_threshold","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},"description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},{"name":"include_nlp_data","in":"query","required":false,"schema":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"description":"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."},{"name":"has_nlp","in":"query","required":false,"schema":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan."},{"name":"theme","in":"query","required":false,"schema":{"title":"Theme","description":"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).","type":"string"},"description":"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)."},{"name":"not_theme","in":"query","required":false,"schema":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match."},{"name":"ORG_entity_name","in":"query","required":false,"schema":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"PER_entity_name","in":"query","required":false,"schema":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"LOC_entity_name","in":"query","required":false,"schema":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"MISC_entity_name","in":"query","required":false,"schema":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"title_sentiment_min","in":"query","required":false,"schema":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"title_sentiment_max","in":"query","required":false,"schema":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_min","in":"query","required":false,"schema":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_max","in":"query","required":false,"schema":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"iptc_tags","in":"query","required":false,"schema":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},{"name":"not_iptc_tags","in":"query","required":false,"schema":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},{"name":"iab_tags","in":"query","required":false,"schema":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},{"name":"not_iab_tags","in":"query","required":false,"schema":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},{"name":"include_translation_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"description":"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."},{"name":"robots_compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusteringSearchResponse"},{"$ref":"#/components/schemas/LatestHeadlinesResponse"}],"title":"Response Latestheadlinesget"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["LatestHeadlines"],"summary":"Get latest headlines","description":"Returns the most recent articles ('headlines') published since a given lookback window, specified via the when parameter, up to now. Supports filtering by language, country, source, and dozens of other parameters; results can optionally be grouped into clusters of similar articles.","operationId":"latestHeadlinesPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestHeadlinesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ClusteringSearchResponse"},{"$ref":"#/components/schemas/LatestHeadlinesResponse"}],"title":"Response Latestheadlinespost"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/authors":{"get":{"tags":["Authors"],"summary":"Search by author","description":"Search for articles written by a given author, matched as a phrase against the article's author byline. Supports filtering by language, country, source, publication date, and dozens of other parameters; does not support full-text query (q) or clustering.","operationId":"authorsGet","parameters":[{"name":"author_name","in":"query","required":true,"schema":{"type":"string","title":"Author Name","description":"Author name to search for. Cannot be empty."},"description":"Author name to search for. Cannot be empty."},{"name":"not_author_name","in":"query","required":false,"schema":{"title":"Not Author Name","description":"Exclude articles written by this author name.","type":"string"},"description":"Exclude articles written by this author name."},{"name":"sources","in":"query","required":false,"schema":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"predefined_sources","in":"query","required":false,"schema":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},{"name":"not_sources","in":"query","required":false,"schema":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"lang","in":"query","required":false,"schema":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"not_lang","in":"query","required":false,"schema":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"countries","in":"query","required":false,"schema":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_countries","in":"query","required":false,"schema":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"from_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},{"name":"to_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},{"name":"published_date_precision","in":"query","required":false,"schema":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone)."},{"name":"by_parse_date","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},"description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"relevancy","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},"description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},{"name":"ranked_only","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},{"name":"from_rank","in":"query","required":false,"schema":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"to_rank","in":"query","required":false,"schema":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"is_headline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},{"name":"is_opinion","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"description":"Filter by whether the article is opinion/editorial content."},{"name":"is_paid_content","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},{"name":"parent_url","in":"query","required":false,"schema":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},{"name":"all_links","in":"query","required":false,"schema":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"description":"Filter for articles that link to any of the given URLs anywhere in their content."},{"name":"all_domain_links","in":"query","required":false,"schema":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"description":"Filter for articles that link to any of the given domains anywhere in their content."},{"name":"all_links_text","in":"query","required":false,"schema":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},{"name":"word_count_min","in":"query","required":false,"schema":{"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set.","type":"integer","minimum":0},"description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},{"name":"word_count_max","in":"query","required":false,"schema":{"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set.","type":"integer","minimum":0},"description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"include_nlp_data","in":"query","required":false,"schema":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"description":"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."},{"name":"has_nlp","in":"query","required":false,"schema":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan."},{"name":"theme","in":"query","required":false,"schema":{"title":"Theme","description":"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).","type":"string"},"description":"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)."},{"name":"not_theme","in":"query","required":false,"schema":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match."},{"name":"title_sentiment_min","in":"query","required":false,"schema":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"title_sentiment_max","in":"query","required":false,"schema":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_min","in":"query","required":false,"schema":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_max","in":"query","required":false,"schema":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"iptc_tags","in":"query","required":false,"schema":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},{"name":"not_iptc_tags","in":"query","required":false,"schema":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},{"name":"iab_tags","in":"query","required":false,"schema":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},{"name":"not_iab_tags","in":"query","required":false,"schema":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},{"name":"include_translation_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"description":"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."},{"name":"robots_compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthorSearchResponse"},{"$ref":"#/components/schemas/FailedAuthorSearchResponse"}],"title":"Response Authorsget"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["Authors"],"summary":"Search by author","description":"Search for articles written by a given author, matched as a phrase against the article's author byline. Supports filtering by language, country, source, publication date, and dozens of other parameters; does not support full-text query (q) or clustering.","operationId":"authorsPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorSearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthorSearchResponse"},{"$ref":"#/components/schemas/FailedAuthorSearchResponse"}],"title":"Response Authorspost"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/search_by_link":{"get":{"tags":["SearchLink"],"summary":"Get articles by URL or ID","description":"Fetch specific articles directly by their NewsCatcher article id(s) or by their exact article link(s), instead of running a full-text search. Provide either ids or links (the two are mutually exclusive and cannot be combined in the same request).","operationId":"searchByLinkGet","parameters":[{"name":"ids","in":"query","required":false,"schema":{"title":"Ids","description":"Article ID(s) to fetch directly (as returned in the id field of a search result). Mutually exclusive with links. Maximum 1000 per request."},"description":"Article ID(s) to fetch directly (as returned in the id field of a search result). Mutually exclusive with links. Maximum 1000 per request."},{"name":"links","in":"query","required":false,"schema":{"title":"Links","description":"Article URL(s) to fetch directly. Must look like a specific article link (at least 3 slashes), not a homepage. Mutually exclusive with ids. Maximum 1000 per request."},"description":"Article URL(s) to fetch directly. Must look like a specific article link (at least 3 slashes), not a homepage. Mutually exclusive with ids. Maximum 1000 per request."},{"name":"from_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"default":"1 month ago","title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 1 month ago if omitted - a longer default window than other endpoints, since this endpoint fetches specific known articles rather than searching recent news."},"description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 1 month ago if omitted - a longer default window than other endpoints, since this endpoint fetches specific known articles rather than searching recent news."},{"name":"to_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"default":"now","title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"include_translation_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"description":"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."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["SearchLink"],"summary":"Get articles by URL or ID","description":"Fetch specific articles directly by their NewsCatcher article id(s) or by their exact article link(s), instead of running a full-text search. Provide either ids or links (the two are mutually exclusive and cannot be combined in the same request).","operationId":"searchByLinkPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchURLRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/sources":{"get":{"tags":["Sources"],"summary":"List news sources","description":"This endpoint allows you to get the list of sources that are available in the database. You can filter the sources by language and country. The maximum number of sources displayed is set according to your plan. You can find the list of plans and their features here: https://newscatcherapi.com/news-api#news-api-pricing source_url and predefined_sources are each mutually exclusive with every other filter field (only include_additional_info may be combined with either of them); at least one of lang, countries, source_url, source_name, or predefined_sources must be provided.","operationId":"sourcesGet","parameters":[{"name":"lang","in":"query","required":false,"schema":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"countries","in":"query","required":false,"schema":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"predefined_sources","in":"query","required":false,"schema":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},{"name":"include_additional_info","in":"query","required":false,"schema":{"title":"Include Additional Info","description":"Includes extra domain-level information (e.g. traffic/audience data) for each source in the response.","type":"boolean"},"description":"Includes extra domain-level information (e.g. traffic/audience data) for each source in the response."},{"name":"from_rank","in":"query","required":false,"schema":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"to_rank","in":"query","required":false,"schema":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"source_name","in":"query","required":false,"schema":{"title":"Source Name","description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},"description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},{"name":"source_url","in":"query","required":false,"schema":{"title":"Source Url","description":"Filter by exact source URL(s). Do not include subdirectories. Mutually exclusive with every other filter field except include_additional_info."},"description":"Filter by exact source URL(s). Do not include subdirectories. Mutually exclusive with every other filter field except include_additional_info."},{"name":"is_news_domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is News Domain","description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},"description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},{"name":"news_domain_type","in":"query","required":false,"schema":{"title":"News Domain Type","description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},"description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},{"name":"news_type","in":"query","required":false,"schema":{"title":"News Type","description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."},"description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SourceExtendedResponse"},{"$ref":"#/components/schemas/FailedSourcesResponse"}],"title":"Response Sourcesget"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"500":{"description":"Internal server error. Please contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["Sources"],"summary":"List news sources","description":"This endpoint allows you to get the list of sources that are available in the database. You can filter the sources by language and country. The maximum number of sources displayed is set according to your plan. You can find the list of plans and their features here: https://newscatcherapi.com/news-api#news-api-pricing source_url and predefined_sources are each mutually exclusive with every other filter field (only include_additional_info may be combined with either of them); at least one of lang, countries, source_url, source_name, or predefined_sources must be provided.","operationId":"sourcesPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/SourceExtendedResponse"},{"$ref":"#/components/schemas/FailedSourcesResponse"}],"title":"Response Sourcespost"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"500":{"description":"Internal server error. Please contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/aggregation_count":{"get":{"tags":["AggregationCount"],"summary":"Aggregate article counts","description":"Returns article counts bucketed over time instead of individual articles. Supports the same filtering parameters as /api/search (keyword, language, country, source, date range, and more); aggregate_by controls the bucket granularity (day, hour, week, or month; defaults to day). Useful for estimating result volume before running a full search.","operationId":"aggregationCountGet","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","title":"Q","description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},"description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},{"name":"search_in","in":"query","required":false,"schema":{"type":"string","default":"title_content","title":"Search In","description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated."},"description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated."},{"name":"predefined_sources","in":"query","required":false,"schema":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},{"name":"sources","in":"query","required":false,"schema":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"not_sources","in":"query","required":false,"schema":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},{"name":"lang","in":"query","required":false,"schema":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"not_lang","in":"query","required":false,"schema":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},{"name":"countries","in":"query","required":false,"schema":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_countries","in":"query","required":false,"schema":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},{"name":"not_author_name","in":"query","required":false,"schema":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"description":"Exclude articles written by any of the given author names."},{"name":"from_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},{"name":"to_","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},{"name":"published_date_precision","in":"query","required":false,"schema":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone)."},{"name":"by_parse_date","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},"description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date."},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"relevancy","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},"description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},{"name":"ranked_only","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},{"name":"from_rank","in":"query","required":false,"schema":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"to_rank","in":"query","required":false,"schema":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"is_headline","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},{"name":"is_opinion","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"description":"Filter by whether the article is opinion/editorial content."},{"name":"is_paid_content","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},{"name":"parent_url","in":"query","required":false,"schema":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},{"name":"all_links","in":"query","required":false,"schema":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"description":"Filter for articles that link to any of the given URLs anywhere in their content."},{"name":"all_domain_links","in":"query","required":false,"schema":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"description":"Filter for articles that link to any of the given domains anywhere in their content."},{"name":"all_links_text","in":"query","required":false,"schema":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},{"name":"word_count_min","in":"query","required":false,"schema":{"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set.","type":"integer","minimum":0},"description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},{"name":"word_count_max","in":"query","required":false,"schema":{"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set.","type":"integer","minimum":0},"description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"clustering_variable","in":"query","required":false,"schema":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'."},{"name":"clustering_enabled","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},{"name":"clustering_threshold","in":"query","required":false,"schema":{"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster.","type":"number"},"description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},{"name":"include_nlp_data","in":"query","required":false,"schema":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"description":"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."},{"name":"has_nlp","in":"query","required":false,"schema":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan."},{"name":"theme","in":"query","required":false,"schema":{"title":"Theme","description":"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).","type":"string"},"description":"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)."},{"name":"not_theme","in":"query","required":false,"schema":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match."},{"name":"ORG_entity_name","in":"query","required":false,"schema":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"PER_entity_name","in":"query","required":false,"schema":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"LOC_entity_name","in":"query","required":false,"schema":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"MISC_entity_name","in":"query","required":false,"schema":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"title_sentiment_min","in":"query","required":false,"schema":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"title_sentiment_max","in":"query","required":false,"schema":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_min","in":"query","required":false,"schema":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_max","in":"query","required":false,"schema":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"iptc_tags","in":"query","required":false,"schema":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},{"name":"not_iptc_tags","in":"query","required":false,"schema":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},{"name":"aggregation_by","in":"query","required":false,"schema":{"title":"Aggregation By","description":"Deprecated alias for aggregate_by - only one of the two may be set; whichever is set is copied to the other.","type":"string"},"description":"Deprecated alias for aggregate_by - only one of the two may be set; whichever is set is copied to the other."},{"name":"aggregate_by","in":"query","required":false,"schema":{"title":"Aggregate By","description":"Time interval to aggregate article counts by: 'day', 'hour', 'week', or 'month'.","type":"string"},"description":"Time interval to aggregate article counts by: 'day', 'hour', 'week', or 'month'."},{"name":"robots_compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},{"name":"exclude_duplicates","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Exclude Duplicates","description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."},"description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregationResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["AggregationCount"],"summary":"Aggregate article counts","description":"Returns article counts bucketed over time instead of individual articles. Supports the same filtering parameters as /api/search (keyword, language, country, source, date range, and more); aggregate_by controls the bucket granularity (day, hour, week, or month; defaults to day). Useful for estimating result volume before running a full search.","operationId":"aggregationCountPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AggregationResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/breaking_news":{"get":{"tags":["BreakingNews"],"summary":"Get breaking news","description":"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.","operationId":"breakingNewsGet","parameters":[{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","default":"relevancy","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},"description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first)."},{"name":"ranked_only","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},{"name":"from_rank","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"to_rank","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":1,"title":"Page","description":"Page number of results to return, starting at 1."},"description":"Page number of results to return, starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":100,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000."},"description":"Number of articles per page. Integer between 1 and 1000."},{"name":"include_nlp_data","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Nlp Data","description":"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."},"description":"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."},{"name":"has_nlp","in":"query","required":false,"schema":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan."},{"name":"theme","in":"query","required":false,"schema":{"title":"Theme","description":"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).","type":"string"},"description":"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)."},{"name":"not_theme","in":"query","required":false,"schema":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match."},{"name":"ORG_entity_name","in":"query","required":false,"schema":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"PER_entity_name","in":"query","required":false,"schema":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"LOC_entity_name","in":"query","required":false,"schema":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"MISC_entity_name","in":"query","required":false,"schema":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan."},{"name":"title_sentiment_min","in":"query","required":false,"schema":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"title_sentiment_max","in":"query","required":false,"schema":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_min","in":"query","required":false,"schema":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"content_sentiment_max","in":"query","required":false,"schema":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan."},{"name":"top_n_articles","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"integer"}],"default":1,"title":"Top N Articles","description":"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."},"description":"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."},{"name":"include_translation_fields","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"description":"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."},{"name":"robots_compliant","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreakingNewsResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}},"post":{"tags":["BreakingNews"],"summary":"Get breaking news","description":"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.","operationId":"breakingNewsPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreakingNewsRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BreakingNewsResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/source-groups":{"get":{"tags":["SourceGroups"],"summary":"List source groups","description":"Returns a paginated list of source groups: named, curated collections of publisher domains. Pass a group's slug to the `source_groups` parameter on `/api/search` to restrict a search to its domains. Only groups published for general use are listed.","operationId":"listSourceGroups","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"1-based page number.","default":1,"title":"Page"},"description":"1-based page number."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Groups per page.","default":100,"title":"Page Size"},"description":"Groups per page."},{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSourceGroupsResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Request validation failed, e.g. an invalid parameter value or a missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"408":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"503":{"description":"The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"429":{"description":"Rate limit exceeded for your plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"499":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}}}}},"/api/subscription":{"get":{"tags":["Subscription"],"summary":"Get subscription info","description":"Returns plan and usage info for the API key used to authenticate this request: subscription status, concurrency and monthly call limits, remaining call quota, and the historical date range your plan allows searching.","operationId":"subscriptionGet","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"500":{"description":"Internal server error. Please contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Subscription"],"summary":"Get subscription info","description":"Returns plan and usage info for the API key used to authenticate this request: subscription status, concurrency and monthly call limits, remaining call quota, and the historical date range your plan allows searching.","operationId":"subscriptionPost","parameters":[{"name":"x-api-token","in":"header","required":true,"schema":{"type":"string","description":"Your NewsCatcher API key, used to authenticate this request.","title":"X-Api-Token"},"description":"Your NewsCatcher API key, used to authenticate this request."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"401":{"description":"Missing or invalid `x-api-token` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"500":{"description":"Internal server error. Please contact support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NCAAPIErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AdditionalSourceInfo":{"properties":{"nb_articles_for_7d":{"title":"Nb Articles For 7D","description":"Number of articles from this source published in the last 7 days, matching the given filters.","type":"integer"},"country":{"title":"Country","description":"Country the source is based in, as an ISO 3166-1 alpha-2 code.","type":"string"},"rank":{"title":"Rank","description":"Source rank - lower values indicate a more authoritative/popular source.","type":"integer"},"is_news_domain":{"title":"Is News Domain","description":"Whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site.","type":"boolean"},"news_domain_type":{"title":"News Domain Type","description":"Domain classification for this source. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'.","type":"string"},"news_type":{"title":"News Type","description":"Detailed content-type classification for this source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'.","type":"string"},"robots_compliant":{"title":"Robots Compliant","description":"Percentage of this source's articles (from the last 7 days) whose robots.txt permitted content extraction at the time of parsing, formatted as a string like '83%'.","type":"string"}},"type":"object","title":"AdditionalSourceInfo","description":"AdditionalSourceInfo DTO class."},"AggregationRequest":{"properties":{"q":{"type":"string","title":"Q","description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},"search_in":{"type":"string","title":"Search In","description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated.","default":"title_content"},"predefined_sources":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"sources":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"not_sources":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"lang":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"not_lang":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"countries":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_countries":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_author_name":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"from_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"to_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"published_date_precision":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"by_parse_date":{"type":"boolean","title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date.","default":false},"sort_by":{"type":"string","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).","default":"relevancy"},"ranked_only":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"from_rank":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"to_rank":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"is_headline":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"is_opinion":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"is_paid_content":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"parent_url":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"all_links":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"all_domain_links":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"all_links_text":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"word_count_min":{"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set.","type":"integer","minimum":0.0},"word_count_max":{"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set.","type":"integer","minimum":0.0},"page":{"type":"integer","minimum":0.0,"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"type":"integer","minimum":0.0,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"clustering_variable":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"clustering_enabled":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"clustering_threshold":{"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster.","type":"number"},"include_nlp_data":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"has_nlp":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"theme":{"title":"Theme","description":"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).","type":"string"},"not_theme":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"ORG_entity_name":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"PER_entity_name":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"LOC_entity_name":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"MISC_entity_name":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"title_sentiment_min":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"title_sentiment_max":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_min":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_max":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"iptc_tags":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"not_iptc_tags":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"aggregation_by":{"title":"Aggregation By","description":"Deprecated alias for aggregate_by - only one of the two may be set; whichever is set is copied to the other.","type":"string"},"aggregate_by":{"title":"Aggregate By","description":"Time interval to aggregate article counts by: 'day', 'hour', 'week', or 'month'.","type":"string"},"robots_compliant":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."},"exclude_duplicates":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Exclude Duplicates","description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."}},"type":"object","required":["q"],"title":"AggregationRequest","description":"AggregationRequest DTO."},"AggregationResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful aggregation request.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of articles matching the query filters, across the full date range (not limited by page_size)."},"page":{"type":"integer","title":"Page","description":"Page number echoed from the request. Aggregation buckets are not paginated - the full set of buckets for the date range is always returned regardless of page."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages implied by total_hits and page_size, for reference only - the aggregations list itself is not split across pages."},"page_size":{"type":"integer","title":"Page Size","description":"Page size echoed from the request. Used only to compute total_pages; does not limit the number of aggregation buckets returned."},"aggregations":{"anyOf":[{"type":"object"},{"items":{"type":"object"},"type":"array"}],"title":"Aggregations","description":"Aggregated article counts as histogram buckets. Shape depends on aggregate_by: typically a mapping (or list of mappings) from a key to a list of `{time_frame, article_count}` entries."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","user_input"],"title":"AggregationResponse","description":"AggregationResponse DTO class."},"AuthorSearchArticleResult":{"properties":{"title":{"type":"string","title":"Title","description":"Article headline/title."},"author":{"title":"Author","description":"Author byline as a single string, as originally extracted from the source.","type":"string"},"authors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Authors","description":"List of author names, parsed from the byline where possible."},"journalists":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"Journalists","description":"List of journalist names, where identified separately from the general author byline."},"published_date":{"title":"Published Date","description":"Date and time the article was originally published.","type":"string"},"published_date_precision":{"title":"Published Date Precision","description":"Precision of published_date: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"updated_date":{"title":"Updated Date","description":"Date and time the article was last updated by its source, if known.","type":"string"},"updated_date_precision":{"title":"Updated Date Precision","description":"Precision of updated_date, using the same scale as published_date_precision.","type":"string"},"parse_date":{"title":"Parse Date","description":"Date and time NewsCatcher parsed/ingested the article. Only included when by_parse_date is used in the request.","type":"string"},"link":{"type":"string","title":"Link","description":"Direct URL to the article."},"domain_url":{"type":"string","title":"Domain Url","description":"Root domain of the article's source (e.g. 'bbc.com')."},"full_domain_url":{"type":"string","title":"Full Domain Url","description":"Full domain of the article's source, including subdomain (e.g. 'news.bbc.co.uk')."},"name_source":{"title":"Name Source","description":"Display name of the news source.","type":"string"},"is_headline":{"type":"string","title":"Is Headline","description":"Whether the article was featured as a headline on its source's homepage at the time of parsing."},"paid_content":{"title":"Paid Content","description":"Whether the article is behind a paywall or marked as sponsored/paid content.","type":"boolean"},"extraction_data":{"title":"Extraction Data","description":"Parent/section URL the article was discovered under (e.g. a category or tag page).","type":"string"},"country":{"title":"Country","description":"Country of the article's source, as an ISO 3166-1 alpha-2 code.","type":"string"},"rights":{"title":"Rights","description":"Copyright/rights holder information, if available.","type":"string"},"rank":{"type":"integer","title":"Rank","description":"Source rank - lower values indicate a more authoritative/popular source."},"media":{"title":"Media","description":"URL of the article's main image, if available.","type":"string"},"language":{"title":"Language","description":"Article language, as a two-letter ISO 639-1 code.","type":"string"},"description":{"title":"Description","description":"Short summary or dek/subheading of the article, as extracted from the source.","type":"string"},"content":{"type":"string","title":"Content","description":"Full text content of the article."},"title_translated_en":{"title":"Title Translated En","description":"Machine-translated English title, for non-English articles. Only included when include_translation_fields is used in the request.","type":"string"},"content_translated_en":{"title":"Content Translated En","description":"Machine-translated English content, for non-English articles. Only included when include_translation_fields is used in the request.","type":"string"},"word_count":{"title":"Word Count","description":"Word count of the article content.","default":0,"type":"integer"},"is_opinion":{"title":"Is Opinion","description":"Whether the article is opinion/editorial content.","type":"boolean"},"twitter_account":{"title":"Twitter Account","description":"Twitter/X account associated with the source or author, if available.","type":"string"},"all_links":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"All Links","description":"URLs linked to from within the article content.","default":[]},"all_domain_links":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"string"}],"title":"All Domain Links","description":"Domains linked to from within the article content.","default":[]},"all_links_data":{"title":"All Links Data","description":"Structured link data (URL and domain pairs) for links within the article content. Only included when all_links_text is used in the request.","items":{},"type":"array"},"nlp":{"title":"Nlp","description":"NLP enrichment data (sentiment, theme, named entities, tags), when available and permitted by your plan.","default":{},"type":"object"},"id":{"type":"string","title":"Id","description":"Unique identifier for this article."},"score":{"type":"number","title":"Score","description":"Elasticsearch relevance score for this result, given the request's query and sort order."},"custom_tags":{"title":"Custom Tags","description":"Organization-specific custom tags applied to this article, if your account has any configured.","type":"object"}},"type":"object","required":["title","link","domain_url","full_domain_url","rank","content","id","score"],"title":"AuthorSearchArticleResult","description":"AuthorSearchArticleResult DTO class."},"AuthorSearchRequest":{"properties":{"author_name":{"type":"string","title":"Author Name","description":"Author name to search for. Cannot be empty."},"not_author_name":{"title":"Not Author Name","description":"Exclude articles written by this author name.","type":"string"},"sources":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"predefined_sources":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"not_sources":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"lang":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"not_lang":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"countries":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_countries":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"from_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"to_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"published_date_precision":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"by_parse_date":{"type":"boolean","title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date.","default":false},"sort_by":{"type":"string","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).","default":"relevancy"},"ranked_only":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"from_rank":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"to_rank":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"is_headline":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"is_opinion":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"is_paid_content":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"parent_url":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"all_links":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"all_domain_links":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"all_links_text":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"word_count_min":{"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set.","type":"integer","minimum":0.0},"word_count_max":{"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set.","type":"integer","minimum":0.0},"page":{"type":"integer","minimum":0.0,"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"type":"integer","minimum":0.0,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"include_nlp_data":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"has_nlp":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"theme":{"title":"Theme","description":"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).","type":"string"},"not_theme":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"title_sentiment_min":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"title_sentiment_max":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_min":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_max":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"iptc_tags":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"not_iptc_tags":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"iab_tags":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"not_iab_tags":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"include_translation_fields":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"robots_compliant":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."}},"type":"object","required":["author_name"],"title":"AuthorSearchRequest","description":"Author search request DTO."},"AuthorSearchResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful search.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of articles matching the query, across all pages."},"page":{"type":"integer","title":"Page","description":"Current page number returned."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages available for this query, given page_size."},"page_size":{"type":"integer","title":"Page Size","description":"Number of articles returned per page."},"articles":{"items":{"type":"object"},"type":"array","title":"Articles","description":"Articles matching the query for this page."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","articles","user_input"],"title":"AuthorSearchResponse","description":"AuthorSearchResponse DTO class."},"BreakingNewsRequest":{"properties":{"sort_by":{"type":"string","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).","default":"relevancy"},"ranked_only":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"from_rank":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"to_rank":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"page":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"include_nlp_data":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Nlp Data","description":"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."},"has_nlp":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"theme":{"title":"Theme","description":"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).","type":"string"},"not_theme":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"ORG_entity_name":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"PER_entity_name":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"LOC_entity_name":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"MISC_entity_name":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"title_sentiment_min":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"title_sentiment_max":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_min":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_max":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"top_n_articles":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Top N Articles","description":"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.","default":1},"include_translation_fields":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"robots_compliant":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."}},"type":"object","title":"BreakingNewsRequest","description":"Breaking news request DTO"},"BreakingNewsResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful breaking news search.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of breaking news events matching the request, across all pages."},"page":{"type":"integer","title":"Page","description":"Current page number returned."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages available for this query, given page_size."},"page_size":{"type":"integer","title":"Page Size","description":"Number of breaking news events returned per page."},"breaking_news_events":{"items":{"type":"object"},"type":"array","title":"Breaking News Events","description":"Breaking news events matching the request, each a cluster of related articles."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","breaking_news_events","user_input"],"title":"BreakingNewsResponse","description":"BreakingNewsResponse DTO class."},"Cluster":{"properties":{"cluster_id":{"type":"string","title":"Cluster Id","description":"Identifier for this cluster of similar articles."},"cluster_size":{"type":"integer","title":"Cluster Size","description":"Number of articles in this cluster."},"articles":{"items":{"type":"object"},"type":"array","title":"Articles","description":"Articles grouped into this cluster."}},"type":"object","required":["cluster_id","cluster_size","articles"],"title":"Cluster","description":"Cluster DTO class."},"ClusteringSearchResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful search.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of articles matching the query, across all pages, before clustering."},"page":{"type":"integer","title":"Page","description":"Current page number returned."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages available for this query, given page_size."},"page_size":{"type":"integer","title":"Page Size","description":"Number of articles requested per page, before grouping into clusters."},"clusters_count":{"type":"integer","title":"Clusters Count","description":"Number of clusters returned."},"clusters":{"items":{"$ref":"#/components/schemas/Cluster"},"type":"array","title":"Clusters","description":"Articles for this page, grouped into clusters of similar content."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","clusters_count","clusters","user_input"],"title":"ClusteringSearchResponse","description":"ClusteringSearchResponse DTO class."},"FailedAuthorSearchResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Explains why no articles were returned.","default":"No Matches for your search"},"total_hits":{"type":"integer","title":"Total Hits","description":"Always 0 - no articles matched the query.","default":0},"page":{"type":"integer","title":"Page","description":"Always 0 - no page of results was produced.","default":0},"total_pages":{"type":"integer","title":"Total Pages","description":"Always 0 - no pages of results were produced.","default":0},"page_size":{"type":"integer","title":"Page Size","description":"Always 0 - no page size applies when there are no results.","default":0},"articles":{"items":{"$ref":"#/components/schemas/AuthorSearchArticleResult"},"type":"array","title":"Articles","description":"Always empty - no articles matched the query.","default":[]},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["user_input"],"title":"FailedAuthorSearchResponse","description":"FailedAuthorSearchResponse DTO class."},"FailedSourcesResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Explains why no sources were returned.","default":"No Matches for your search"},"sources":{"items":{"type":"string"},"type":"array","title":"Sources","description":"Always empty - no sources matched the filters.","default":[]},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["user_input"],"title":"FailedSourcesResponse","description":"FailedSourcesResponse DTO class."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LatestHeadlinesRequest":{"properties":{"when":{"type":"string","title":"When","description":"How far back to look for headlines, replacing from_/to_ for this endpoint. Format: '<N>d' for N days ago or '<N>h' for N hours ago (e.g. '7d', '24h'). Results run from this point up to now.","default":"7d"},"by_parse_date":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date.","default":false},"sort_by":{"type":"string","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).","default":"relevancy"},"lang":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"not_lang":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"countries":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_countries":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"sources":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"predefined_sources":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"not_sources":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"not_author_name":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"ranked_only":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"is_headline":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"is_opinion":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"is_paid_content":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"parent_url":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"all_links":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"all_domain_links":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"all_links_text":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"word_count_min":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},"word_count_max":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},"page":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"clustering_variable":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"clustering_enabled":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"clustering_threshold":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},"include_nlp_data":{"title":"Include Nlp Data","description":"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.","type":"boolean"},"has_nlp":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"theme":{"title":"Theme","description":"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).","type":"string"},"not_theme":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"ORG_entity_name":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"PER_entity_name":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"LOC_entity_name":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"MISC_entity_name":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"title_sentiment_min":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"title_sentiment_max":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_min":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_max":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"iptc_tags":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"not_iptc_tags":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"iab_tags":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"not_iab_tags":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"include_translation_fields":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"robots_compliant":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."}},"type":"object","title":"LatestHeadlinesRequest","description":"Latest headlines request DTO."},"LatestHeadlinesResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful search.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of articles matching the query, across all pages."},"page":{"type":"integer","title":"Page","description":"Current page number returned."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages available for this query, given page_size."},"page_size":{"type":"integer","title":"Page Size","description":"Number of articles returned per page."},"articles":{"items":{"type":"object"},"type":"array","title":"Articles","description":"Articles matching the query for this page."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","articles","user_input"],"title":"LatestHeadlinesResponse","description":"LatestHeadlinesResponse DTO class."},"ListSourceGroupsResponse":{"properties":{"source_groups":{"items":{"$ref":"#/components/schemas/SourceGroupResponse"},"type":"array","title":"Source Groups"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"}},"type":"object","required":["source_groups","total","page","page_size"],"title":"ListSourceGroupsResponse","description":"One page of the catalogue."},"NCAAPIErrorResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable explanation of the error."},"status_code":{"type":"integer","title":"Status Code","description":"Status code repeated in the response body."},"status":{"type":"string","title":"Status","description":"Short status label, e.g. 'Validation error'."}},"type":"object","required":["message","status_code","status"],"title":"NCAAPIErrorResponse","description":"Documents the error body shape every exception handler in main.py returns."},"SearchRequest":{"properties":{"q":{"type":"string","title":"Q","description":"Search query using Lucene-like syntax: supports boolean operators (AND, OR, NOT, and &&, ||, ! as aliases), exact phrase matching with double quotes, grouping with parentheses, and wildcards. Cannot be empty."},"search_in":{"type":"string","title":"Search In","description":"Which fields to search the query against. Up to 2 values from: title, content, title_content, summary (summary requires an NLP plan). NLP/translation plans additionally allow searching translated fields: title_translated, content_translated, summary_translated, title_content_translated.","default":"title_content"},"predefined_sources":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"sources":{"title":"Sources","description":"Filter by source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"source_groups":{"title":"Source Groups","description":"Restrict the search to the publisher domains of one or more curated source groups, given by slug (e.g. 'top_100_us_finance'). Call GET /api/source-groups for the available slugs. Combine multiple as a comma-separated string or array; their domains are merged. Behaves like `sources` once resolved, including suppressing `countries`."},"not_sources":{"title":"Not Sources","description":"Exclude articles from these source domain(s) (e.g. 'bbc.com'). Do not include subdirectories."},"lang":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"not_lang":{"title":"Not Lang","description":"Exclude articles in these language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"countries":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_countries":{"title":"Not Countries","description":"Exclude sources from these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"not_author_name":{"title":"Not Author Name","description":"Exclude articles written by any of the given author names."},"from_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 7 days ago at midnight UTC if omitted."},"to_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted."},"published_date_precision":{"title":"Published Date Precision","description":"Filter by how precisely the published date is known: 'full' (exact date and time), 'date' (day known, time unknown), or 'timezone unknown' (date and time known, but not the timezone).","type":"string"},"by_parse_date":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"By Parse Date","description":"When true, the date range and sorting apply to the date NewsCatcher parsed/ingested the article instead of its published date.","default":false},"sort_by":{"type":"string","title":"Sort By","description":"Sort order for results: 'relevancy' (default, best text match first), 'date' (newest first), '-date' (oldest first), or 'rank' (most authoritative source first).","default":"relevancy"},"ranked_only":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Ranked Only","description":"When true, only returns articles from sources that have a known rank (excludes unranked sources)."},"from_rank":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"to_rank":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999."},"is_headline":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Headline","description":"Filter by whether the article was featured as a headline on its source's homepage at the time of parsing."},"is_opinion":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Opinion","description":"Filter by whether the article is opinion/editorial content."},"is_paid_content":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is Paid Content","description":"Filter by whether the article is behind a paywall or marked as sponsored/paid content."},"parent_url":{"title":"Parent Url","description":"Filter by the parent/section URL(s) the article was discovered under (e.g. a category or tag page), rather than the root domain."},"all_links":{"title":"All Links","description":"Filter for articles that link to any of the given URLs anywhere in their content."},"all_domain_links":{"title":"All Domain Links","description":"Filter for articles that link to any of the given domains anywhere in their content."},"all_links_text":{"title":"All Links Text","description":"Filter for articles that contain a link with the given anchor text anywhere in their content."},"word_count_min":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Min","description":"Minimum article word count. Must be non-negative, and less than word_count_max if both are set."},"word_count_max":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Word Count Max","description":"Maximum article word count. Must be non-negative, and greater than word_count_min if both are set."},"page":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"anyOf":[{"type":"string"},{"type":"integer"}],"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"clustering_variable":{"title":"Clustering Variable","description":"Which article field to base clustering similarity on: 'content', 'title', or 'summary'.","type":"string"},"clustering_enabled":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Clustering Enabled","description":"When true, groups similar articles into clusters in the response instead of returning a flat list. A single request's date range cannot span both before and after 2026-01-01, since clustering uses different embeddings on either side of that date."},"clustering_threshold":{"anyOf":[{"type":"number"},{"type":"string"}],"title":"Clustering Threshold","description":"Similarity threshold for clustering, greater than 0 and up to 1 inclusive. Higher values require greater similarity to group articles into the same cluster."},"include_nlp_data":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Nlp Data","description":"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."},"has_nlp":{"title":"Has Nlp","description":"When true, only returns articles that have NLP enrichment data. Requires an NLP plan.","type":"boolean"},"theme":{"title":"Theme","description":"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).","type":"string"},"not_theme":{"title":"Not Theme","description":"Exclude articles with any of the given themes. Same allowed values as theme, but does not support ' AND ' grouping - always excludes on any match.","type":"string"},"ORG_entity_name":{"title":"Org Entity Name","description":"Filter articles that mention the given organization name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"PER_entity_name":{"title":"Per Entity Name","description":"Filter articles that mention the given person name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"LOC_entity_name":{"title":"Loc Entity Name","description":"Filter articles that mention the given location name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"MISC_entity_name":{"title":"Misc Entity Name","description":"Filter articles that mention the given miscellaneous entity name(s) in NLP-extracted named entities. Requires an NLP plan.","type":"string"},"title_sentiment_min":{"title":"Title Sentiment Min","description":"Minimum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"title_sentiment_max":{"title":"Title Sentiment Max","description":"Maximum sentiment score for the article title, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_min":{"title":"Content Sentiment Min","description":"Minimum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"content_sentiment_max":{"title":"Content Sentiment Max","description":"Maximum sentiment score for the article content, from -1 (most negative) to 1 (most positive), as determined by NLP analysis. Requires an NLP plan.","type":"number"},"iptc_tags":{"title":"Iptc Tags","description":"Filter by IPTC media topic tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IPTC tagging."},"not_iptc_tags":{"title":"Not Iptc Tags","description":"Exclude articles tagged with any of the given IPTC media topic tag(s). Requires an NLP plan with IPTC tagging."},"source_name":{"title":"Source Name","description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},"iab_tags":{"title":"Iab Tags","description":"Filter by IAB content taxonomy tag(s). Comma-separated values are OR'd together; values joined with ' AND ' within one comma-separated group must all match the same article. Requires an NLP plan with IAB tagging."},"not_iab_tags":{"title":"Not Iab Tags","description":"Exclude articles tagged with any of the given IAB content taxonomy tag(s). Requires an NLP plan with IAB tagging."},"exclude_duplicates":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Exclude Duplicates","description":"Excludes duplicate articles from results, keeping only the original publisher's version. Only available for English articles published on or after 2024-05-13, and non-English articles published on or after 2025-03-17."},"additional_domain_info":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Additional Domain Info","description":"Includes extra domain-level information (e.g. traffic/audience data) for each article's source, where available."},"is_news_domain":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is News Domain","description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},"news_domain_type":{"title":"News Domain Type","description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},"news_type":{"title":"News Type","description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."},"include_translation_fields":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."},"robots_compliant":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Robots Compliant","description":"Filter by whether the source's robots.txt permitted content extraction: true returns only compliant articles, false returns only non-compliant ones."}},"type":"object","required":["q"],"title":"SearchRequest","description":"Search request DTO"},"SearchResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Always 'ok' for a successful search.","default":"ok"},"total_hits":{"type":"integer","title":"Total Hits","description":"Total number of articles matching the query, across all pages."},"page":{"type":"integer","title":"Page","description":"Current page number returned."},"total_pages":{"type":"integer","title":"Total Pages","description":"Total number of pages available for this query, given page_size."},"page_size":{"type":"integer","title":"Page Size","description":"Number of articles returned per page."},"articles":{"items":{"type":"object"},"type":"array","title":"Articles","description":"Articles matching the query for this page."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["total_hits","page","total_pages","page_size","articles","user_input"],"title":"SearchResponse","description":"SearchResponse DTO class."},"SearchURLRequest":{"properties":{"ids":{"title":"Ids","description":"Article ID(s) to fetch directly (as returned in the id field of a search result). Mutually exclusive with links. Maximum 1000 per request."},"links":{"title":"Links","description":"Article URL(s) to fetch directly. Must look like a specific article link (at least 3 slashes), not a homepage. Mutually exclusive with ids. Maximum 1000 per request."},"from_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"From ","description":"Start of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to 1 month ago if omitted - a longer default window than other endpoints, since this endpoint fetches specific known articles rather than searching recent news.","default":"1 month ago"},"to_":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"title":"To ","description":"End of the date range (inclusive). Accepts natural-language and common date formats (e.g. 'YYYY/mm/dd', 'YYYY/mm/dd HH:MM:SS', '1 day ago'). Defaults to now if omitted.","default":"now"},"page":{"type":"integer","minimum":0.0,"title":"Page","description":"Page number of results to return, starting at 1.","default":1},"page_size":{"type":"integer","minimum":0.0,"title":"Page Size","description":"Number of articles per page. Integer between 1 and 1000.","default":100},"include_translation_fields":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Include Translation Fields","description":"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."}},"type":"object","title":"SearchURLRequest","description":"Search URL Request DTO."},"SourceExtendedResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable summary of the results, e.g. the number of sources found or the maximum number of sources your plan allows."},"sources":{"items":{"anyOf":[{"$ref":"#/components/schemas/SourceInfo"},{"type":"string"}]},"type":"array","title":"Sources","description":"List of sources matching the request filters."},"user_input":{"type":"object","title":"User Input","description":"Echo of the request parameters that produced this response."}},"type":"object","required":["message","sources","user_input"],"title":"SourceExtendedResponse","description":"SourceExtendedResponse DTO class."},"SourceGroupResponse":{"properties":{"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"description":{"title":"Description","type":"string"}},"type":"object","required":["slug","name"],"title":"SourceGroupResponse","description":"One source group."},"SourceInfo":{"properties":{"name_source":{"title":"Name Source","description":"Display name of the news source.","type":"string"},"domain_url":{"type":"string","title":"Domain Url","description":"Root domain of the source (e.g. 'bbc.com')."},"logo":{"title":"Logo","description":"URL of the source's logo image, if available.","type":"string"},"additional_info":{"description":"Extra domain-level details for this source. Only included when include_additional_info is used in the request.","allOf":[{"$ref":"#/components/schemas/AdditionalSourceInfo"}],"title":"Additional Info"}},"type":"object","required":["domain_url"],"title":"SourceInfo","description":"\"SourceInfo DTO class."},"SourcesRequest":{"properties":{"lang":{"title":"Lang","description":"Filter by article language(s), as two-letter ISO 639-1 codes (e.g. 'en', 'es')."},"countries":{"title":"Countries","description":"Filter by source country/countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'GB')."},"predefined_sources":{"title":"Predefined Sources","description":"Filter by a fixed number of top-ranked sources per country, instead of specifying exact source domains. Format: 'top N XX' where N is 1-10000 and XX is a two-letter country code or 'global' (e.g. 'top 100 US'). Combine multiple values as a comma-separated string or array (e.g. 'top 100 US, top 1000 global')."},"include_additional_info":{"title":"Include Additional Info","description":"Includes extra domain-level information (e.g. traffic/audience data) for each source in the response.","type":"boolean"},"from_rank":{"title":"From Rank","description":"Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"to_rank":{"title":"To Rank","description":"Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999.","type":"integer"},"source_name":{"title":"Source Name","description":"Filter by the display name of the news source (as opposed to its domain), matched case-insensitively as a substring."},"source_url":{"title":"Source Url","description":"Filter by exact source URL(s). Do not include subdirectories. Mutually exclusive with every other filter field except include_additional_info."},"is_news_domain":{"anyOf":[{"type":"string"},{"type":"boolean"}],"title":"Is News Domain","description":"Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site."},"news_domain_type":{"title":"News Domain Type","description":"Filter by domain classification. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'."},"news_type":{"title":"News Type","description":"Filter by detailed content-type classification of the source. One of: 'Tech News and Updates', 'Sports News and Blogs', 'News and Blogs', 'E-commerce and Product Information', 'Educational News', 'Press Releases', 'Corporate News', 'Gaming News and Blogs', 'Entertainment and Media News', 'Health and Medical News', 'Government and Municipal News', 'Real Estate News', 'Automotive News and Blogs', 'News Aggregators', 'Fashion and Lifestyle', 'Local News and Community Events', 'Music and Radio', 'Reviews', 'Blogs and Magazines', 'Political News', 'Non-Profit and Organization News', 'Event News', 'General News Outlets', 'Gambling News', 'Travel and Lifestyle', 'Finance and Investment', 'Other', 'Specific News Type', 'Pure News Outlet', 'Corporate News Section'."}},"type":"object","title":"SourcesRequest","description":"Sources request DTO"},"SubscriptionResponse":{"properties":{"active":{"type":"boolean","title":"Active","description":"Whether this API key's subscription is currently active."},"calls_per_seconds":{"title":"Calls Per Seconds","description":"Maximum number of concurrent API requests allowed per second under your plan. Exceeding this returns a 429 Too Many Requests error.","type":"integer"},"plan_name":{"type":"string","title":"Plan Name","description":"Name of your subscription plan (e.g. 'v3_basic', 'v3_nlp')."},"usage_assigned_calls":{"title":"Usage Assigned Calls","description":"Total number of API calls assigned to your plan for the current billing period.","type":"integer"},"usage_remaining_calls":{"title":"Usage Remaining Calls","description":"Number of API calls remaining in the current billing period. Requests are rejected once this reaches zero.","type":"integer"},"historical_days":{"title":"Historical Days","description":"Number of days of historical article data your plan allows querying.","type":"integer"}},"type":"object","required":["active","plan_name"],"title":"SubscriptionResponse","description":"SubscriptionResponse DTO class."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}