--- title: "List news sources" method: POST path: "/api/sources" tags: ["Sources"] --- # List news sources `POST /api/sources` ## Request - Base URL: `https://v3-api.newscatcherapi.com` (the document declares no server; this is the origin it was published from) - URL: `https://v3-api.newscatcherapi.com/api/sources` - Auth: none declared. Required headers: `x-api-token` 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. ## Headers - `x-api-token` string, required: Your NewsCatcher API key, used to authenticate this request. ## Request body - SourcesRequest: Sources request DTO - `lang` unknown - `countries` unknown - `predefined_sources` unknown - `include_additional_info` boolean: Includes extra domain-level information (e.g. traffic/audience data) for each source in the response. - `from_rank` integer: Minimum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999. - `to_rank` integer: Maximum source rank (lower rank = more authoritative/popular source). Integer between 1 and 999999. - `source_name` unknown - `source_url` unknown - `is_news_domain` union: Filter by whether the domain is classified as a genuine news domain, as opposed to e.g. a blog, forum, or non-news site. - string - boolean - `news_domain_type` unknown - `news_type` unknown ## Response `200` Successful Response - union - SourceExtendedResponse: SourceExtendedResponse DTO class. - `message` string, required: Human-readable summary of the results, e.g. the number of sources found or the maximum number of sources your plan allows. - `sources` union[], required: List of sources matching the request filters. - union - SourceInfo: "SourceInfo DTO class. - `name_source` string: Display name of the news source. - `domain_url` string, required: Root domain of the source (e.g. 'bbc.com'). - `logo` string: URL of the source's logo image, if available. - `additional_info` AdditionalSourceInfo: AdditionalSourceInfo DTO class. - `nb_articles_for_7d` integer: Number of articles from this source published in the last 7 days, matching the given filters. - `country` string: Country the source is based in, as an ISO 3166-1 alpha-2 code. - `rank` integer: Source rank - lower values indicate a more authoritative/popular source. - `is_news_domain` boolean: 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` string: Domain classification for this source. One of: 'Original Content', 'Aggregator', 'Other', 'Press Releases', 'Republisher'. - `news_type` string: 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'. - `robots_compliant` string: 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%'. - string - `user_input` object, required: Echo of the request parameters that produced this response. - FailedSourcesResponse: FailedSourcesResponse DTO class. - `message` string: Explains why no sources were returned. - `sources` string[]: Always empty - no sources matched the filters. - `user_input` object, required: Echo of the request parameters that produced this response. ## Other responses - `401`: Missing or invalid `x-api-token` header. - `403`: A supplied parameter isn't included in your subscription plan, or the requested date range exceeds your plan's allowed history window. Also returned to free tier (trial) keys whose trial has ended or whose included calls are used up. - `408`: Your query reached the search backend but did not finish within 30 seconds. Narrow the date range, lower page_size, or simplify the query. Note this covers only genuinely slow queries - if the backend could not be reached at all the response is 503, which is retryable as-is. - `422`: Request validation failed, e.g. an invalid parameter value or a missing required field. - `429`: Rate limit exceeded for your plan. - `499`: The HTTP status line is 499, but the response body's own `status_code` field reads 422 - a known quirk of this API's validation-error handling for cases not covered by the standard 422 path, not a documentation error. - `500`: Internal server error. Please contact support. - `503`: The search backend could not be reached, so the query was never executed. Nothing about the request needs to change - retry it unchanged. --- [API](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api.md) - [All operations](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/llms.txt) - [OpenAPI document](https://skmtc.dev/newscatcherapi/apis/newscatcher-v3-production-api/revisions/a3950aefb3e5?raw)