> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve sources > Retrieves the list of sources available in the database. You can filter the sources by language, country, and more. ## OpenAPI ````yaml news-api-v3 post /api/sources openapi: 3.1.0 info: title: NewsCatcher News API description: > NewsCatcher News API provides programmatic access to a continuously updated global news index. It includes endpoints for article search, latest headlines, breaking news, author search, aggregation counts, and source discovery. ## Key features - **Full-text search**: Query articles by keyword, phrase, language, country, source, publication date, sentiment, and more using Boolean operators and advanced filters. - **NLP enrichment**: Articles include theme classification, sentiment scores, and named entity recognition (people, organizations, locations). - **Article clustering**: Group similar articles into clusters to reduce noise and surface unique stories. - **Deduplication**: Exclude duplicate articles from results to keep datasets clean and relevant. - **Source intelligence**: Discover and filter news sources by domain, type, rank, and geographic origin. For documentation, integration guides, and SDKs, visit the [developer portal](https://wwwnewscatcherapi.com/docs). termsOfService: https://newscatcherapi.com/terms-of-service contact: name: Maksym Sugonyaka email: maksym@newscatcherapi.com version: 3.24.0 servers: - url: https://v3-api.newscatcherapi.com description: News API production server security: - ApiKeyAuth: [] tags: - name: Search description: Operations to search for articles. externalDocs: description: Search for articles by keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search/search-articles-get - name: LatestHeadlines description: Operations to retrieve latest headlines. externalDocs: description: >- Retrieve the latest headlines since a specified date, with filtering options. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/latest-headlines/retrieve-latest-headlines-get - name: BreakingNews description: Operations to retrieve breaking news articles. externalDocs: description: Retrieve breaking news articles. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/breaking-news/breaking-news-get - name: Authors description: Operations to search by author. externalDocs: description: Search for articles by author. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/authors/search-articles-by-author-get - name: SearchByLink description: Operations to search by link or ID. externalDocs: description: Search for articles by link or ID. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/search-by-link/search-articles-by-links-or-ids-get - name: Sources description: Operations to retrieve news sources. externalDocs: description: >- Retrieve the list of available sources, filtered by language and country. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/sources/retrieve-sources-get - name: AggregationCount description: Operations to aggregate news counts. externalDocs: description: >- Aggregate news counts based on specified criteria such as keyword, language, country, source, and more. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/aggregation-count/get-aggregation-count-by-interval-get - name: Subscription description: Operations to get subscription info. externalDocs: description: Retrieve information about your subscription plan. url: >- https://www.newscatcherapi.com/docs/news-api/api-reference/subscription/retrieve-subscription-plan-information-get externalDocs: description: Find out more about NewsCatcher News API url: https://www.newscatcherapi.com/docs paths: /api/sources: post: tags: - Sources summary: Retrieve sources description: >- Retrieves the list of sources available in the database. You can filter the sources by language, country, and more. operationId: sourcesPost requestBody: $ref: '#/components/requestBodies/SourcesRequestBody' responses: '200': $ref: '#/components/responses/SourcesResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/ForbiddenError' '408': $ref: '#/components/responses/RequestTimeoutError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' components: requestBodies: SourcesRequestBody: description: >- Request body for searching news sources based on specified criteria such as language, country, and more. required: true content: application/json: schema: type: object properties: lang: $ref: '#/components/schemas/Lang' countries: $ref: '#/components/schemas/Countries' predefined_sources: $ref: '#/components/schemas/PredefinedSources' source_name: $ref: '#/components/schemas/SourceName' source_url: $ref: '#/components/schemas/SourceUrl' include_additional_info: $ref: '#/components/schemas/IncludeAdditionalInfo' is_news_domain: $ref: '#/components/schemas/IsNewsDomain' news_domain_type: $ref: '#/components/schemas/NewsDomainType' news_type: $ref: '#/components/schemas/NewsType' from_rank: $ref: '#/components/schemas/FromRank' to_rank: $ref: '#/components/schemas/ToRank' example: predefined_sources: top 10 US responses: SourcesResponse: description: >- A successful response containing a list of news sources that match the specified criteria. content: application/json: schema: $ref: '#/components/schemas/SourcesResponseDto' BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid JSON in request body status_code: 400 status: Bad request UnauthorizedError: description: Unauthorized - Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' example: message: >- The 'x-api-token' parameter has an invalid value. Please provide a valid API key. status_code: 401 status: Unauthorized ForbiddenError: description: Forbidden - Server refuses action content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Your plan request date range cannot be greater than 400 days status_code: 403 status: Forbidden RequestTimeoutError: description: Request timeout content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Request timed out after 30 seconds status_code: 408 status: Request timeout ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Invalid date format status_code: 422 status: Validation error RateLimitError: description: Too many requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Max API requests concurrency reached status_code: 429 status: Too many requests InternalServerError: description: Internal server error content: text/plain: schema: type: string example: Internal Server Error schemas: Lang: oneOf: - type: string example: en,es - type: array items: type: string example: - en - es description: > The language(s) of the search. The only accepted format is the two-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) code. To select multiple languages, use a comma-separated string or an array of strings. To learn more, see [Enumerated parameters > Language](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#language-lang-and-not-lang). Countries: oneOf: - type: string example: US,CA - type: array items: type: string example: - US - CA description: > The countries where the news publisher is located. The accepted format is the two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. To select multiple countries, use a comma-separated string or an array of strings. To learn more, see [Enumerated parameters > Country](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#country-country-and-not-country). PredefinedSources: oneOf: - type: string example: top 50 US, top 20 GB - type: array items: type: string example: - top 50 US - top 20 GB description: > Predefined top news sources per country. Format: start with the word `top`, followed by the number of desired sources, and then the two-letter country code [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Multiple countries with the number of top sources can be specified as a comma-separated string or an array of strings. SourceName: oneOf: - type: string example: sport, tech - type: array items: type: string example: - sport - tech description: > Specifies terms to search within the source names. To specify multiple terms, use a comma-separated string or an array of strings. **Note**: The search does not require an exact match and returns all sources that include the specified terms anywhere in their names. You can use any word, phrase, or outlet name, such as `"sport"`, or `"new york times"`. For example, using `"sport"` as a term returns sources like `"Motorsport"`, `"Dot Esport"`, and `"Tuttosport"`. SourceUrl: oneOf: - type: string example: bbc.com,nytimes.com - type: array items: type: string example: - bbc.com - nytimes.com description: > The domains of the news publication to search for. To specify multiple news sources, use a comma-separated string or an array of strings. **Caution**: When specifying the `source_url` parameter, you can only use `include_additional_info` as an extra parameter. example: bbc.com IncludeAdditionalInfo: type: boolean description: > If true, returns the following additional datapoints about each news source: - `nb_articles_for_7d`: The number of articles published by the source in the last week. - `country`: Source country of origin. - `rank`: SEO rank. - `is_news_domain`: Boolean indicating if the source is a news domain. - `news_domain_type`: Type of news domain (e.g., "Original Content"). - `news_type`: Category of news (e.g., "General News Outlets"). - `robots_compliant`: Percentage of domain articles that comply with robots.txt scraping rules (0-100%). example: true IsNewsDomain: type: boolean description: | If true, filters results to include only news domains. example: true NewsDomainType: type: string enum: - Original Content - Aggregator - Press Releases - Republisher - Other description: | Filters results based on the news domain type. Possible values are: - `Original Content`: Sources that produce their own content. - `Aggregator`: Sources that collect content from various other sources. - `Press Releases`: Sources primarily publishing press releases. - `Republisher`: Sources that republish content from other sources. - `Other`: Sources that don't fit into main categories. example: Original Content NewsType: oneOf: - type: string example: General News Outlets,Tech News and Updates - type: array items: type: string example: - General News Outlets - Tech News and Updates description: > Filters results based on the news type. Multiple types can be specified using a comma-separated string or an array of strings. For a complete list of available news types, see [Enumerated parameters > News type](https://www.newscatcherapi.com/docs/news-api/api-reference/enumerated-parameters#news-type-news-type). FromRank: type: integer minimum: 1 maximum: 999999 default: 1 format: int32 description: > The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source. example: 100 ToRank: type: integer minimum: 1 maximum: 999999 default: 999999 format: int32 description: > The highest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source. example: 100 SourcesResponseDto: title: Sources Response description: > The response model for a successful `Sources` request retrieving news sources matching the specified criteria. Response field behavior: - Required fields are guaranteed to be present and non-null. - Optional fields may be `null` or `undefined` if the data point is not presented or couldn't be extracted during processing. required: - message - sources - user_input type: object properties: message: title: Message description: A message indicating the result of the request. type: string sources: title: Sources description: A list of news sources that match the specified criteria. type: array items: anyOf: - $ref: '#/components/schemas/SourceInfo' - type: string user_input: title: User Input description: The user input parameters for the request. type: object Error: type: object properties: message: type: string description: A detailed description of the error. status_code: type: integer description: The HTTP status code of the error. status: type: string description: A short description of the status code. required: - message - status_code - status SourceInfo: title: Source Info description: The data model for information about a news source. required: - domain_url type: object properties: name_source: title: Name Source description: The name of the news source. type: string domain_url: title: Domain Url description: The domain URL of the news source. type: string logo: title: Logo description: The logo of the news source. type: string additional_info: $ref: '#/components/schemas/AdditionalSourceInfo' AdditionalSourceInfo: title: Additional Source Info description: The data model for additional information about a news source. type: object properties: nb_articles_for_7d: title: Nb Articles For 7D description: >- The number of articles published by the source in the last seven days. type: integer country: title: Country description: The country of origin of the news source. type: string rank: title: Rank description: The SEO rank of the news source. type: integer is_news_domain: title: Is News Domain description: Indicates whether the source is a news domain. type: boolean news_domain_type: title: News Domain Type description: The type of news domain. type: string news_type: title: News Type description: The category of news provided by the source. type: string robots_compliant: title: Robots Compliant description: > Percentage of domain articles that comply with robots.txt scraping rules (0-100%). type: string example: 100% example: nb_articles_for_7d: 153 country: US rank: 117 is_news_domain: true news_domain_type: Original Content news_type: General News Outlets robots_compliant: 100% securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token description: > API Key to authenticate requests. To access the API, include your API key in the `x-api-token` header. To obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly. ````