fern-api · Mar 19, 2026
diff --git a/.fern/metadata.json b/.fern/metadata.json
@@ -1,7 +1,7 @@
 {
-  "cliVersion": "4.29.0",
+  "cliVersion": "4.37.2",
   "generatorName": "fernapi/fern-python-sdk",
-  "generatorVersion": "4.64.0",
+  "generatorVersion": "5.0.3",
   "generatorConfig": {
     "client": {
       "class_name": "BaseNewscatcherApi",
@@ -10,6 +10,6 @@
       "exported_filename": "client.py"
     }
   },
-  "originGitCommit": "bbd2054c67ad246b017399f96faf58cf6737bf01",
-  "sdkVersion": "2.0.2"
+  "originGitCommit": "f2b6fc1078e742776b706484940ced855d0f0e74",
+  "sdkVersion": "3.0.0"
 }
diff --git a/.fernignore b/.fernignore
@@ -15,4 +15,5 @@ test-mock-mode.sh
 mypy.ini
 
 # CI/CD
-.github/workflows/ci.yml
+.github/workflows/ci.yml
+changelog.md
diff --git a/changelog.md b/changelog.md
@@ -0,0 +1,3 @@
+## 3.0.0 - 2026-03-19
+* The SDK now requires Python 3.10 or higher. Python 3.8 and 3.9 are no longer supported. All type aliases now include comprehensive documentation with usage examples and links to relevant guides.
+
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ dynamic = ["version"]
 
 [tool.poetry]
 name = "newscatcher-sdk"
-version = "2.0.2"
+version = "3.0.0"
 description = ""
 readme = "README.md"
 authors = []
@@ -14,8 +14,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -39,16 +37,16 @@ packages = [
 Repository = 'https://github.com/Newscatcher/newscatcher-python'
 
 [tool.poetry.dependencies]
-python = "^3.8"
+python = "^3.10"
 httpx = ">=0.21.2"
 pydantic = ">= 1.9.2"
 pydantic-core = ">=2.18.2"
 typing_extensions = ">= 4.0.0"
 
 [tool.poetry.group.dev.dependencies]
 mypy = "==1.13.0"
-pytest = "^7.4.0"
-pytest-asyncio = "^0.23.5"
+pytest = "^8.2.0"
+pytest-asyncio = "^1.0.0"
 pytest-xdist = "^3.6.1"
 python-dateutil = "^2.9.0"
 types-python-dateutil = "^2.9.0.20240316"

diff --git a/src/newscatcher/core/client_wrapper.py b/src/newscatcher/core/client_wrapper.py
@@ -27,12 +27,12 @@ def get_headers(self) -> typing.Dict[str, str]:
         import platform
 
         headers: typing.Dict[str, str] = {
-            "User-Agent": "newscatcher-sdk/2.0.2",
+            "User-Agent": "newscatcher-sdk/3.0.0",
             "X-Fern-Language": "Python",
             "X-Fern-Runtime": f"python/{platform.python_version()}",
             "X-Fern-Platform": f"{platform.system().lower()}/{platform.release()}",
             "X-Fern-SDK-Name": "newscatcher-sdk",
-            "X-Fern-SDK-Version": "2.0.2",
+            "X-Fern-SDK-Version": "3.0.0",
             **(self.get_custom_headers() or {}),
         }
         headers["x-api-token"] = self.api_key

diff --git a/src/newscatcher/types/additional_domain_info.py b/src/newscatcher/types/additional_domain_info.py
@@ -1,3 +1,9 @@
 # This file was auto-generated by Fern from our API Definition.
 
 AdditionalDomainInfo = bool
+"""
+If true, includes additional domain information in the response for each article:
+- `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., `"News and Blogs"`).
+"""
diff --git a/src/newscatcher/types/articles_dto.py b/src/newscatcher/types/articles_dto.py
@@ -5,3 +5,6 @@
 from .article_entity import ArticleEntity
 
 ArticlesDto = typing.List[ArticleEntity]
+"""
+A list of articles matching the search criteria.
+"""
diff --git a/src/newscatcher/types/author_name.py b/src/newscatcher/types/author_name.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 AuthorName = str
+"""
+The name of the author to search for. This parameter returns exact matches only.
+"""
diff --git a/src/newscatcher/types/by_parse_date.py b/src/newscatcher/types/by_parse_date.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ByParseDate = bool
+"""
+If true, the `from_` and `to_` parameters use article parse dates instead of published dates. Additionally, the `parse_date` variable is added to the output for each article object.
+"""
diff --git a/src/newscatcher/types/clustering_enabled.py b/src/newscatcher/types/clustering_enabled.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ClusteringEnabled = bool
+"""
+Determines whether to group similar articles into clusters. If true, the API returns clustered results.
+
+To learn more, see [Clustering news articles](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/clustering-news-articles).
+"""
diff --git a/src/newscatcher/types/clustering_threshold.py b/src/newscatcher/types/clustering_threshold.py
@@ -1,3 +1,13 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ClusteringThreshold = float
+"""
+Sets the similarity threshold for grouping articles into clusters. A lower value creates more inclusive clusters, while a higher value requires greater similarity between articles.
+
+For example:
+- `0.3`: Results in larger, more diverse clusters.
+- `0.6`: Balances cluster size and article similarity (default).
+- `0.9`: Creates smaller, tightly related clusters.
+
+To learn more, see [Clustering news articles](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/clustering-news-articles).
+"""
diff --git a/src/newscatcher/types/content_sentiment_max.py b/src/newscatcher/types/content_sentiment_max.py
@@ -1,3 +1,13 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ContentSentimentMax = float
+"""
+Filters articles based on the maximum sentiment score of their content.
+
+Range is `-1.0` to `1.0`, where:
+- Negative values indicate negative sentiment.
+- Positive values indicate positive sentiment.
+- Values close to 0 indicate neutral sentiment.
+
+To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
+"""
diff --git a/src/newscatcher/types/content_sentiment_min.py b/src/newscatcher/types/content_sentiment_min.py
@@ -1,3 +1,13 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ContentSentimentMin = float
+"""
+Filters articles based on the minimum sentiment score of their content.
+
+Range is `-1.0` to `1.0`, where:
+- Negative values indicate negative sentiment.
+- Positive values indicate positive sentiment.
+- Values close to 0 indicate neutral sentiment.
+
+To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
+"""
diff --git a/src/newscatcher/types/exclude_duplicates.py b/src/newscatcher/types/exclude_duplicates.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 ExcludeDuplicates = bool
+"""
+If true, excludes duplicate and highly similar articles from the search results. If false, returns all relevant articles, including duplicates. 
+
+To learn more, see [Articles deduplication](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/articles-deduplication).
+"""
diff --git a/src/newscatcher/types/from_rank.py b/src/newscatcher/types/from_rank.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 FromRank = int
+"""
+The lowest boundary of the rank of a news website to filter by. A lower rank indicates a more popular source.
+"""
diff --git a/src/newscatcher/types/has_nlp.py b/src/newscatcher/types/has_nlp.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 HasNlp = bool
+"""
+If true, filters results to include only articles that have NLP data.
+
+To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
+"""
diff --git a/src/newscatcher/types/include_additional_info.py b/src/newscatcher/types/include_additional_info.py
@@ -1,3 +1,13 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IncludeAdditionalInfo = bool
+"""
+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%).
+"""
diff --git a/src/newscatcher/types/include_nlp_data.py b/src/newscatcher/types/include_nlp_data.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IncludeNlpData = bool
+"""
+If true, includes an NLP object for each article in the response. This object provides results of NLP analysis, including article theme, summary, sentiment, tags, and named entity recognition if available.
+
+To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
+"""
diff --git a/src/newscatcher/types/include_translation_fields.py b/src/newscatcher/types/include_translation_fields.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IncludeTranslationFields = bool
+"""
+If true, includes English translation fields in the response (`title_translated_en`, `content_translated_en`, and NLP translation fields).
+"""
diff --git a/src/newscatcher/types/is_headline.py b/src/newscatcher/types/is_headline.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IsHeadline = bool
+"""
+If true, only returns articles that were posted on the home page of a given news domain.
+"""
diff --git a/src/newscatcher/types/is_news_domain.py b/src/newscatcher/types/is_news_domain.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IsNewsDomain = bool
+"""
+If true, filters results to include only news domains.
+"""
diff --git a/src/newscatcher/types/is_opinion.py b/src/newscatcher/types/is_opinion.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IsOpinion = bool
+"""
+If true, returns only opinion pieces. If false, excludes opinion-based articles and returns news only.
+"""
diff --git a/src/newscatcher/types/is_paid_content.py b/src/newscatcher/types/is_paid_content.py
@@ -1,3 +1,10 @@
 # This file was auto-generated by Fern from our API Definition.
 
 IsPaidContent = bool
+"""
+Filters articles by content completeness.
+
+If false, returns only articles for which full-text content is publicly available. If true, returns all indexed articles, including those where only partial content is publicly available (e.g., headlines, summaries, or preview paragraphs from paywalled sources).
+
+**Note**: NewsCatcher indexes content that is publicly accessible and available for crawling in accordance with publisher access controls (e.g., robots.txt and similar mechanisms). For paywalled sources, only content that publishers make publicly available (such as headlines, summaries, or preview text) is indexed. NewsCatcher does not bypass paywalls, authentication systems, or other technical access restrictions.
+"""
diff --git a/src/newscatcher/types/loc_entity_name.py b/src/newscatcher/types/loc_entity_name.py
@@ -1,3 +1,11 @@
 # This file was auto-generated by Fern from our API Definition.
 
 LocEntityName = str
+"""
+Filters articles that mention specific location names, as identified by NLP analysis.
+
+- To specify multiple locations, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. 
+- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).
+
+To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).
+"""
diff --git a/src/newscatcher/types/misc_entity_name.py b/src/newscatcher/types/misc_entity_name.py
@@ -1,3 +1,11 @@
 # This file was auto-generated by Fern from our API Definition.
 
 MiscEntityName = str
+"""
+Filters articles that mention other named entities not falling under person, organization, or location categories. Includes events, nationalities, products, works of art, and more.
+
+- To specify multiple entities, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. 
+- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).
+
+To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).
+"""
diff --git a/src/newscatcher/types/named_entity_list.py b/src/newscatcher/types/named_entity_list.py
@@ -5,3 +5,6 @@
 from .named_entity_list_item import NamedEntityListItem
 
 NamedEntityList = typing.List[NamedEntityListItem]
+"""
+A list of named entities identified in the article.
+"""
diff --git a/src/newscatcher/types/ner_name.py b/src/newscatcher/types/ner_name.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 NerName = str
+"""
+The name of person, organization, location, product or other named entity to search for. To specify multiple names use a comma-separated string. 
+
+Example: `"Tesla, Amazon"`
+"""
diff --git a/src/newscatcher/types/not_theme.py b/src/newscatcher/types/not_theme.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 NotTheme = str
+"""
+Inverse of the `theme` parameter. Excludes articles based on their general topic, as determined by NLP analysis. To exclude multiple themes, use a comma-separated string.
+
+To learn more, see [NLP features](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/nlp-features).
+"""
diff --git a/src/newscatcher/types/org_entity_name.py b/src/newscatcher/types/org_entity_name.py
@@ -1,3 +1,11 @@
 # This file was auto-generated by Fern from our API Definition.
 
 OrgEntityName = str
+"""
+Filters articles that mention specific organization names, as identified by NLP analysis. 
+
+- To specify multiple organizations, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. 
+- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).
+
+To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).
+"""
diff --git a/src/newscatcher/types/page.py b/src/newscatcher/types/page.py
@@ -1,3 +1,8 @@
 # This file was auto-generated by Fern from our API Definition.
 
 Page = int
+"""
+The page number to scroll through the results. Use for pagination, as a single API response can return up to 1,000 articles. 
+
+For details, see [How to paginate large datasets](https://www.newscatcherapi.com/docs/news-api/how-to/paginate-large-datasets).
+"""
diff --git a/src/newscatcher/types/page_size.py b/src/newscatcher/types/page_size.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 PageSize = int
+"""
+The number of articles to return per page.
+"""
diff --git a/src/newscatcher/types/per_entity_name.py b/src/newscatcher/types/per_entity_name.py
@@ -1,3 +1,11 @@
 # This file was auto-generated by Fern from our API Definition.
 
 PerEntityName = str
+"""
+Filters articles that mention specific person names, as identified by NLP analysis. 
+
+- To specify multiple names, use `AND`, `OR`, `NOT` operators, and `\"` escape literals for exact matches. 
+- To search in translations, combine with the translation options of the `search_in` parameter (e.g., `title_content_translated`).
+
+To learn more, see [Search by entity](https://www.newscatcherapi.com/docs/news-api/how-to/search-by-entity).
+"""
diff --git a/src/newscatcher/types/published_date_precision.py b/src/newscatcher/types/published_date_precision.py
@@ -1,3 +1,9 @@
 # This file was auto-generated by Fern from our API Definition.
 
 PublishedDatePrecision = str
+"""
+The precision of the published date. There are three types:
+- `full`: The day and time of an article is correctly identified with the appropriate timezone.
+- `timezone unknown`: The day and time of an article is correctly identified without timezone.
+- `date`: Only the day is identified without an exact time.
+"""
diff --git a/src/newscatcher/types/q.py b/src/newscatcher/types/q.py
@@ -1,3 +1,16 @@
 # This file was auto-generated by Fern from our API Definition.
 
 Q = str
+"""
+The keyword(s) to search for in articles. Query syntax supports logical operators (`AND`, `OR`, `NOT`) and wildcards:
+
+- For exact phrases, use escaped quotes: `\"technology news\"`
+- Use `*` for wildcards: `technolog*` (cannot start with `*`)
+- Use `+` to include and `-` to exclude: `+Apple`, `-Google`
+- Boolean operators: `technology AND (Apple OR Microsoft) NOT Google`
+- Forbidden characters: `[` `]` `/` `\\` `:` `^` and URL-encoded equivalents
+
+**Note:** The API automatically inserts `AND` operators between standalone terms, so strings like `"machine learning"` become `"machine AND learning"`. To avoid syntax errors (especially in queries with `OR` operators), use literal escape `"\"machine learning\""`.
+
+For detailed syntax rules, see [Advanced querying](https://www.newscatcherapi.com/docs/news-api/guides-and-concepts/advanced-querying).
+"""
diff --git a/src/newscatcher/types/ranked_only.py b/src/newscatcher/types/ranked_only.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 RankedOnly = bool
+"""
+If true, limits the search to sources ranked in the top 1 million online websites. If false, includes unranked sources which are assigned a rank of 999999.
+"""
diff --git a/src/newscatcher/types/robots_compliant.py b/src/newscatcher/types/robots_compliant.py
@@ -1,3 +1,6 @@
 # This file was auto-generated by Fern from our API Definition.
 
 RobotsCompliant = bool
+"""
+If true, returns only articles that comply with the publisher's robots.txt rules. If false, returns only articles that do not comply with robots.txt rules. If omitted, returns all articles regardless of compliance status.
+"""
diff --git a/src/newscatcher/types/search_in.py b/src/newscatcher/types/search_in.py
@@ -1,3 +1,10 @@
 # This file was auto-generated by Fern from our API Definition.
 
 SearchIn = str
+"""
+The article fields to search in. Use a comma-separated string for multiple options, with a maximum of 2 in a single request.
+
+Available options: 
+- Standard fields: `title`, `content`, `summary`, `title_content`
+- Translation fields: `title_translated`, `content_translated`, `summary_translated`, `title_content_translated`
+"""
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## 3.0.0 - 2026-03-19
		* The SDK now requires Python 3.10 or higher. Python 3.8 and 3.9 are no longer supported. All type aliases now include comprehensive documentation with usage examples and links to relevant guides.