oscatcher · Mar 17, 2026 · Mar 17, 2026
diff --git a/.fern/metadata.json b/.fern/metadata.json
@@ -0,0 +1,10 @@
+{
+  "cliVersion": "4.29.0",
+  "generatorName": "fernapi/fern-java-sdk",
+  "generatorVersion": "3.44.1",
+  "generatorConfig": {
+    "publish-to": "central"
+  },
+  "originGitCommit": "bbd2054c67ad246b017399f96faf58cf6737bf01",
+  "sdkVersion": "2.0.0"
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,6 +2,10 @@ name: ci
 
 on: [push]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   compile:
     runs-on: ubuntu-latest

diff --git a/README.md b/README.md
@@ -1,12 +1,35 @@
 # Newscatcher Java Library
 
-[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-SDK%20generated%20by%20Fern-brightgreen)](https://github.com/fern-api/fern) [![Maven Central](https://img.shields.io/maven-central/v/com.newscatcherapi/newscatcher-sdk)](https://central.sonatype.com/artifact/com.newscatcherapi/newscatcher-sdk)
-
-The Newscatcher Java library lets you access the Newscatcher API from Java or Kotlin.
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2FNewscatcher%2Fnewscatcher-java)
+[![Maven Central](https://img.shields.io/maven-central/v/com.newscatcherapi/newscatcher-sdk)](https://central.sonatype.com/artifact/com.newscatcherapi/newscatcher-sdk)
+
+The Newscatcher Java library provides convenient access to the Newscatcher APIs from Java.
+
+## Table of Contents
+
+- [Documentation](#documentation)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Reference](#reference)
+- [Usage](#usage)
+- [Error Handling](#error-handling)
+- [Advanced Features](#advanced-features)
+- [Example Requests](#example-requests)
+- [Environments](#environments)
+- [Base Url](#base-url)
+- [Exception Handling](#exception-handling)
+- [Advanced](#advanced)
+  - [Custom Client](#custom-client)
+  - [Retries](#retries)
+  - [Timeouts](#timeouts)
+  - [Custom Headers](#custom-headers)
+  - [Access Raw Response Data](#access-raw-response-data)
+- [Contributing](#contributing)
+- [Release Notes](#release-notes)
 
 ## Documentation
 
-Find the complete API reference [here](https://www.newscatcherapi.com/docs/v3/api-reference).
+API reference documentation is available [here](https://www.newscatcherapi.com/docs/news-api/api-reference/overview).
 
 ## Requirements
 
@@ -16,43 +39,56 @@ This library requires Java 8 or above.
 
 ### Gradle
 
-Add this dependency to your `build.gradle`:
+Add the dependency in your `build.gradle` file:
 
 ```groovy
 dependencies {
-    implementation 'com.newscatcherapi:newscatcher-sdk:1.1.0'
+  implementation 'com.newscatcherapi:newscatcher-sdk'
 }
 ```
 
 ### Maven
 
-Add this dependency to your `pom.xml`:
+Add the dependency in your `pom.xml` file:
 
 ```xml
 <dependency>
-    <groupId>com.newscatcherapi</groupId>
-    <artifactId>newscatcher-sdk</artifactId>
-    <version>1.1.0</version>
+  <groupId>com.newscatcherapi</groupId>
+  <artifactId>newscatcher-sdk</artifactId>
+  <version>2.0.0</version>
 </dependency>
 ```
 
+## Reference
+
+A full reference for this library is available [here](https://github.com/Newscatcher/newscatcher-java/blob/HEAD/./reference.md).
+
 ## Usage
 
-Build and use the client like this:
+Instantiate and use the client with the following:
 
 ```java
-import com.newscatcher.api.NewscatcherApiClient;
-import com.newscatcher.api.resources.search.requests.SearchPostRequest;
-import java.util.Arrays;
+package com.example.usage;
 
-NewscatcherApiClient client = NewscatcherApiClient.builder()
-    .apiKey("YOUR_API_KEY")
-    .build();
-
-client.search().post(SearchPostRequest.builder()
-    .q("renewable energy")
-    .lang(Arrays.asList("en"))
-    .build());
+import com.newscatcher.api.NewscatcherApiClient;
+import com.newscatcher.api.resources.search.requests.PostSearchRequest;
+
+public class Example {
+    public static void main(String[] args) {
+        NewscatcherApiClient client = NewscatcherApiClient
+            .builder()
+            .apiKey("<value>")
+            .build();
+
+        client.search().post(
+            PostSearchRequest
+                .builder()
+                .q("\"supply chain\" AND Amazon NOT China")
+                .pageSize(1)
+                .build()
+        );
+    }
+}
 ```
 
 ## Error Handling
@@ -157,16 +193,163 @@ client.authors().post(AuthorsPostRequest.builder()
     .build());
 ```
 
-## Contributing
+## Environments
 
-We generate this SDK programmatically, so we can't accept direct code contributions. Instead:
+This SDK allows you to configure different environments for API requests.
 
-1. [Open an issue](https://github.com/Newscatcher/newscatcher-java/issues) to discuss your ideas with us first.
-2. If you want to show an implementation, create a PR as a proof of concept.
-3. We'll work with you to implement the changes in our generator.
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+import com.newscatcher.api.core.Environment;
 
-On the other hand, contributions to the README are always very welcome!
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .environment(Environment.Default)
+    .build();
+```
+
+## Base Url
+
+You can set a custom base URL when constructing the client.
+
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .url("https://example.com")
+    .build();
+```
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), an API exception will be thrown.
+
+```java
+import com.newscatcher.api.core.NewscatcherApiApiException;
+
+try{
+    client.search().post(...);
+} catch (NewscatcherApiApiException e){
+    // Do something with the API exception...
+}
+```
+
+## Advanced
+
+### Custom Client
+
+This SDK is built to work with any instance of `OkHttpClient`. By default, if no client is provided, the SDK will construct one.
+However, you can pass your own client like so:
+
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+import okhttp3.OkHttpClient;
+
+OkHttpClient customClient = ...;
+
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .httpClient(customClient)
+    .build();
+```
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2). Before defaulting to exponential backoff, the SDK will first attempt to respect
+the `Retry-After` header (as either in seconds or as an HTTP date), and then the `X-RateLimit-Reset` header
+(as a Unix timestamp in epoch seconds); failing both of those, it will fall back to exponential backoff.
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `maxRetries` client option to configure this behavior.
+
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .maxRetries(1)
+    .build();
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+import com.newscatcher.api.core.RequestOptions;
+
+// Client level
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .timeout(60)
+    .build();
 
+// Request level
+client.search().post(
+    ...,
+    RequestOptions
+        .builder()
+        .timeout(60)
+        .build()
+);
+```
+
+### Custom Headers
+
+The SDK allows you to add custom headers to requests. You can configure headers at the client level or at the request level.
+
+```java
+import com.newscatcher.api.NewscatcherApiClient;
+import com.newscatcher.api.core.RequestOptions;
+
+// Client level
+NewscatcherApiClient client = NewscatcherApiClient
+    .builder()
+    .addHeader("X-Custom-Header", "custom-value")
+    .addHeader("X-Request-Id", "abc-123")
+    .build();
+;
+
+// Request level
+client.search().post(
+    ...,
+    RequestOptions
+        .builder()
+        .addHeader("X-Request-Header", "request-value")
+        .build()
+);
+```
+
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `withRawResponse()` method.
+The `withRawResponse()` method returns a raw client that wraps all responses with `body()` and `headers()` methods.
+(A normal client's `response` is identical to a raw client's `response.body()`.)
+
+```java
+PostHttpResponse response = client.search().withRawResponse().post(...);
+
+System.out.println(response.body());
+System.out.println(response.headers().get("X-My-Header"));
+```
+
+## Contributing
+
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!
 ## Release Notes
 
 For release notes and changelog, visit our [GitHub releases page](https://github.com/Newscatcher/newscatcher-java/releases).
+
diff --git a/build.gradle b/build.gradle
@@ -14,10 +14,10 @@ repositories {
 }
 
 dependencies {
-    api 'com.squareup.okhttp3:okhttp:4.12.0'
-    api 'com.fasterxml.jackson.core:jackson-databind:2.17.2'
-    api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.17.2'
-    api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.17.2'
+    api 'com.squareup.okhttp3:okhttp:5.2.1'
+    api 'com.fasterxml.jackson.core:jackson-databind:2.18.6'
+    api 'com.fasterxml.jackson.datatype:jackson-datatype-jdk8:2.18.6'
+    api 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.18.6'
     testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
     testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
     testImplementation 'org.junit.jupiter:junit-jupiter-params:5.8.2'
@@ -47,7 +47,7 @@ java {
 
 group = 'com.newscatcherapi'
 
-version = '1.2.0'
+version = '2.0.0'
 
 jar {
     dependsOn(":generatePomFileForMavenPublication")
@@ -78,7 +78,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'com.newscatcherapi'
             artifactId = 'newscatcher-sdk'
-            version = '1.2.0'
+            version = '2.0.0'
             from components.java
             pom {
                 name = 'newscatcher'
@@ -121,9 +121,10 @@ sonatypeCentralUpload {
 }
 
 signing {
-    def signingKeyId = "$System.env.MAVEN_SIGNATURE_SECRET_KEY"
+    def signingKeyId = "$System.env.MAVEN_SIGNATURE_KID"
+    def signingKey = "$System.env.MAVEN_SIGNATURE_SECRET_KEY"
     def signingPassword = "$System.env.MAVEN_SIGNATURE_PASSWORD"
-    useInMemoryPgpKeys(signingKeyId, signingPassword)
+    useInMemoryPgpKeys(signingKeyId, signingKey, signingPassword)
     sign publishing.publications.maven
 }