Java SDK

Java SDK provides access to the CatchAll API from Java applications.

Installation

Gradle
Maven

dependencies {
    implementation 'com.newscatcherapi:newscatcher-catchall-sdk:3.0.0'
}

<dependency>
    <groupId>com.newscatcherapi</groupId>
    <artifactId>newscatcher-catchall-sdk</artifactId>
    <version>3.0.0</version>
</dependency>

Quickstart

Get started with CatchAll in three steps:

Initialize the client

import com.newscatcher.catchall.CatchAllApi;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

Create a job

import com.newscatcher.catchall.resources.jobs.requests.SubmitRequestDto;

var job = client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("AI company acquisitions")
        .limit(10)
        .build()
);
String jobId = job.getJobId();

Wait and retrieve results

import com.newscatcher.catchall.types.StatusResponseDto;
import com.newscatcher.catchall.types.PublicJobStatus;

final int POLL_INTERVAL_MS = 60000;

// Poll for completion
while (true) {
    StatusResponseDto status = client.jobs().getJobStatus(jobId);
    if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
        break;
    }
    Thread.sleep(POLL_INTERVAL_MS);
}

// Get results
var results = client.jobs().getJobResults(jobId);
System.out.println("Found " + results.getValidRecords().orElse(0) + " valid records");

Jobs process asynchronously and typically complete in 10-15 minutes. See the Quickstart for a complete walkthrough.

Working with jobs

Get suggestions
Create and track
Continue jobs
Early results
List jobs

Preview suggested validators, enrichments, and date ranges before creating a job:

import com.newscatcher.catchall.CatchAllApiClient;
import com.newscatcher.catchall.resources.jobs.requests.InitializeRequestDto;
import com.newscatcher.catchall.types.InitializeResponseDto;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;

CatchAllApiClient client = CatchAllApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

InitializeResponseDto suggestions = client.jobs().initialize(
    InitializeRequestDto.builder()
        .query("AI company acquisitions")
        .context("Focus on deal size and acquiring company details")
        .build()
);

ObjectMapper mapper = new ObjectMapper();
mapper.enable(SerializationFeature.INDENT_OUTPUT);
System.out.println(mapper.writeValueAsString(suggestions));

Show suggestions response

{
  "validators": [
    {
      "name": "is_acquisition_event",
      "description": "true if article describes a completed or announced acquisition",
      "type": "boolean"
    },
    {
      "name": "involves_ai_company",
      "description": "true if acquiring or acquired company is in AI sector",
      "type": "boolean"
    }
  ],
  "enrichments": [
    {
      "name": "acquirer_company",
      "description": "Extract the acquiring company name",
      "type": "company"
    },
    {
      "name": "acquired_company",
      "description": "Extract the acquired company name",
      "type": "company"
    },
    {
      "name": "deal_value",
      "description": "Extract acquisition price if mentioned",
      "type": "number"
    },
    {
      "name": "announcement_date",
      "description": "Extract date of announcement",
      "type": "date"
    },
    {
      "name": "acquirer_details",
      "description": "Extract details about the acquiring company",
      "type": "text"
    }
  ],
  "start_date": "2026-02-01T14:12:57.292205+00:00",
  "end_date": "2026-02-06T14:12:57.292205+00:00",
  "date_modification_message": [
    "No dates were provided; using a default window of 5 days (2026-02-01 to 2026-02-06)."
  ]
}

To learn more, see the Initialize endpoint.

Submit a query and track its progress:

import com.newscatcher.catchall.resources.jobs.requests.SubmitRequestDto;
import com.newscatcher.catchall.types.StatusResponseDto;
import com.newscatcher.catchall.types.PublicJobStatus;

final int POLL_INTERVAL_MS = 60000;

// Create job with custom validators and enrichments
var job = client.jobs().createJob(    
    SubmitRequestDto.builder()
        .query("AI company acquisitions")
        .context("Focus on deal size and acquiring company details")
        .limit(10)
        .validators(
            ValidatorSchema.builder()
                .name("is_acquisition_event")
                .description("true if article describes a completed or announced acquisition")
                .type("boolean")
                .build()
        )
        .enrichments(
            EnrichmentSchema.builder()
                .name("acquirer_company")
                .description("Extract the acquiring company name")
                .type(EnrichmentType.COMPANY)
                .build(),
            EnrichmentSchema.builder()
                .name("acquired_company")
                .description("Extract the acquired company name")
                .type(EnrichmentType.COMPANY)
                .build(),
            EnrichmentSchema.builder()
                .name("deal_value")
                .description("Extract acquisition price if mentioned")
                .type(EnrichmentType.NUMBER)
                .build()
        )
        .build()
);
System.out.println("Job created: " + job.getJobId());

// Monitor progress
String jobId = job.getJobId();
while (true) {
    StatusResponseDto status = client.jobs().getJobStatus(jobId);

    if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
        break;
    }

    status.getSteps().stream()
        .filter(step -> !step.getCompleted().orElse(false))
        .findFirst()
        .ifPresent(step -> System.out.println(String.format(
            "Step %d/7: %s",
            step.getOrder(),
            step.getStatus()
        )));

    Thread.sleep(POLL_INTERVAL_MS);
}

// Retrieve results
var results = client.jobs().getJobResults(jobId);
System.out.println("\nFound " + results.getValidRecords().orElse(0) + " valid records");
results.getAllRecords().ifPresent(records ->
    records.forEach(record -> System.out.println("  " + record.getRecordTitle()))
);

Validators and enrichments are optional. If not provided, the system generates them automatically based on your query.

Extend processing limits for completed jobs:

import com.newscatcher.catchall.resources.jobs.requests.ContinueRequestDto;
import com.newscatcher.catchall.types.ContinueResponseDto;

final int POLL_INTERVAL_MS = 60000;

// Continue job to process more records
ContinueResponseDto continued = client.jobs().continueJob(
    ContinueRequestDto.builder()
        .jobId(jobId)
        .newLimit(50)
        .build()
);
System.out.println(String.format(
    "Continued: %s -> %s records",
    continued.getPreviousLimit(),
    continued.getNewLimit()
));

// Wait for completion
while (true) {
    StatusResponseDto status = client.jobs().getJobStatus(jobId);
    if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
        break;
    }
    Thread.sleep(POLL_INTERVAL_MS);
}

// Get final results
var finalResults = client.jobs().getJobResults(jobId);
System.out.println("Total: " + finalResults.getValidRecords().orElse(0) + " valid records");

Use limit parameter when creating jobs to start with fewer records for quick testing. Continue the job if you need more records after reviewing initial results.

Retrieve partial results during the enriching stage:

import com.newscatcher.catchall.types.PullJobResponseDto;

final int POLL_INTERVAL_MS = 60000;

while (true) {
    StatusResponseDto status = client.jobs().getJobStatus(jobId);

    if (PublicJobStatus.ENRICHING.equals(status.getStatus().orElse(null)) || 
        PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
        
        PullJobResponseDto results = client.jobs().getJobResults(jobId);
        
        if (results.getValidRecords().orElse(0) > 0) {
            System.out.println(String.format(
                "Progress: %d/%d validated, %d valid",
                results.getProgressValidated().orElse(0),
                results.getCandidateRecords().orElse(0),
                results.getValidRecords().orElse(0)
            ));
        }

        if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
            break;
        }
    }

    Thread.sleep(POLL_INTERVAL_MS);
}

Retrieve all jobs created by your account:

import com.newscatcher.catchall.types.ListUserJobsResponseDto;
import java.util.List;

List<ListUserJobsResponseDto> jobs = client.jobs().getUserJobs();

jobs.forEach(job -> {
    System.out.println(String.format(
        "Job %s: %s (%s)",
        job.getJobId(),
        job.getQuery(),
        job.getStatus()
    ));
});

Complete example with all features

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.resources.jobs.requests.SubmitRequestDto;
import com.newscatcher.catchall.resources.jobs.requests.ContinueRequestDto;
import com.newscatcher.catchall.types.StatusResponseDto;
import com.newscatcher.catchall.types.PullJobResponseDto;
import com.newscatcher.catchall.types.PublicJobStatus;
import com.newscatcher.catchall.core.NewscatcherApiApiException;

public class CompleteExample {
    public static void main(String[] args) {
        final int POLL_INTERVAL_MS = 60000;

        CatchAllApi client = CatchAllApi.builder()
            .apiKey("YOUR_API_KEY")
            .timeout(30)
            .maxRetries(3)
            .build();

        try {
            // Create job with custom enrichments
            var job = client.jobs().createJob(
                SubmitRequestDto.builder()
                    .query("AI company acquisitions")
                    .context("Focus on deal size and acquiring company details")
                    .limit(10)
                    .enrichments(
                        EnrichmentSchema.builder()
                            .name("acquirer_company")
                            .description("Extract the acquiring company name")
                            .type(EnrichmentType.COMPANY)
                            .build(),
                        EnrichmentSchema.builder()
                            .name("deal_value")
                            .description("Extract acquisition price if mentioned")
                            .type(EnrichmentType.NUMBER)
                            .build()
                    )
                    .build()
            );
            String jobId = job.getJobId();
            System.out.println("Job created: " + jobId);

            // Poll with early results access
            while (true) {
                StatusResponseDto status = client.jobs().getJobStatus(jobId);

                if (PublicJobStatus.ENRICHING.equals(status.getStatus().orElse(null)) || 
                    PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
                    
                    PullJobResponseDto results = client.jobs().getJobResults(jobId);
                    if (results.getValidRecords().orElse(0) > 0) {
                        System.out.println(String.format(
                            "Progress: %d valid records",
                            results.getValidRecords().orElse(0)
                        ));
                    }

                    if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
                        break;
                    }
                }

                Thread.sleep(POLL_INTERVAL_MS);
            }

            // Continue if needed
            PullJobResponseDto results = client.jobs().getJobResults(jobId);
            if (results.getValidRecords().orElse(0) >= 10) {
                client.jobs().continueJob(
                    ContinueRequestDto.builder()
                        .jobId(jobId)
                        .newLimit(50)
                        .build()
                );

                while (true) {
                    StatusResponseDto status = client.jobs().getJobStatus(jobId);
                    if (PublicJobStatus.COMPLETED.equals(status.getStatus().orElse(null))) {
                        break;
                    }
                    Thread.sleep(POLL_INTERVAL_MS);
                }

                results = client.jobs().getJobResults(jobId);
            }

            // Display results
            System.out.println("\nFinal: " + results.getValidRecords().orElse(0) + " valid records");
            results.getAllRecords().ifPresent(records ->
                records.forEach(record -> System.out.println("  " + record.getRecordTitle()))
            );

        } catch (NewscatcherApiApiException e) {
            System.err.println("Status: " + e.statusCode());
            System.err.println("Error: " + e.body());
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            System.err.println("Operation interrupted");
        }
    }
}

Working with monitors

Automate recurring queries with scheduled execution.

Create monitor
Update monitor
Pause/Resume
List monitors
Retrieve results

Create a monitor from a completed job:

import com.newscatcher.catchall.resources.monitors.requests.CreateMonitorRequestDto;
import com.newscatcher.catchall.types.CreateMonitorResponseDto;
import com.newscatcher.catchall.types.WebhookDto;
import com.newscatcher.catchall.types.WebhookDtoMethod;
import java.util.Map;

CreateMonitorResponseDto monitor = client.monitors().createMonitor(
    CreateMonitorRequestDto.builder()
        .referenceJobId(jobId)
        .schedule("every day at 12 PM UTC")
        .webhookIds(List.of("a1b2c3d4-e5f6-7890-abcd-ef1234567890"))
        .build()
);
System.out.println("Monitor created: " + monitor.getMonitorId().orElse("N/A"));

Monitors require a minimum 24-hour interval between executions. Learn more in the Monitors documentation.

Update webhook configuration for an existing monitor:

import com.newscatcher.catchall.resources.monitors.requests.UpdateMonitorRequestDto;
import com.newscatcher.catchall.types.UpdateMonitorResponseDto;

String monitorId = monitor.getMonitorId().orElseThrow();

UpdateMonitorResponseDto updated = client.monitors().updateMonitor(
    monitorId,
    UpdateMonitorRequestDto.builder()
        .webhookIds(List.of("b2c3d4e5-f6a7-8901-bcde-f12345678901"))
        .limit(100)
        .build()
);
System.out.println("Monitor updated: " + updated.getStatus());

Control monitor execution:

String monitorId = monitor.getMonitorId().orElseThrow();

// Pause monitor
client.monitors().disableMonitor(monitorId);
System.out.println("Monitor paused");

// Resume monitor
client.monitors().enableMonitor(monitorId);
System.out.println("Monitor resumed");

Retrieve all monitors for your account:

import com.newscatcher.catchall.types.ListMonitorsResponseDto;

ListMonitorsResponseDto monitors = client.monitors().listMonitors();

System.out.println("Total monitors: " + monitors.getTotalMonitors());
monitors.getMonitors().forEach(m -> {
    String status = m.getEnabled() ? "active" : "paused";
    System.out.println(String.format("%s: %s", m.getMonitorId(), status));
});

Access aggregated results from all monitor executions:

import com.newscatcher.catchall.resources.monitors.requests.ListMonitorJobsRequest;
import com.newscatcher.catchall.resources.monitors.types.ListMonitorJobsResponse;
import com.newscatcher.catchall.types.PullMonitorResponseDto;

String monitorId = monitor.getMonitorId().orElseThrow();

// List execution history
ListMonitorJobsResponse jobs = client.monitors().listMonitorJobs(
    monitorId,
    ListMonitorJobsRequest.builder()
        .sort("desc")
        .build()
);
System.out.println("Monitor executed " + jobs.getTotalJobs() + " jobs");

// Get all collected records
PullMonitorResponseDto results = client.monitors().pullMonitorResults(monitorId);
System.out.println("Total records: " + results.getRecords().orElse(0));

results.getAllRecords().ifPresent(records ->
    records.forEach(record -> {
        System.out.println("  " + record.getRecordTitle());
        System.out.println("  Added: " + record.getAddedOn());
    })
);

Complete monitor example

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.resources.monitors.requests.CreateMonitorRequestDto;
import com.newscatcher.catchall.resources.monitors.requests.UpdateMonitorRequestDto;
import com.newscatcher.catchall.resources.monitors.requests.ListMonitorJobsRequest;
import com.newscatcher.catchall.resources.monitors.types.ListMonitorJobsResponse;
import com.newscatcher.catchall.types.CreateMonitorResponseDto;
import com.newscatcher.catchall.types.UpdateMonitorResponseDto;
import com.newscatcher.catchall.types.ListMonitorsResponseDto;
import com.newscatcher.catchall.types.PullMonitorResponseDto;
import com.newscatcher.catchall.types.WebhookDto;
import com.newscatcher.catchall.types.WebhookDtoMethod;
import com.newscatcher.catchall.core.NewscatcherApiApiException;
import java.util.Map;

public class MonitorExample {
    public static void main(String[] args) {
        CatchAllApi client = CatchAllApi.builder()
            .apiKey("YOUR_API_KEY")
            .build();

        try {
            // Create monitor from completed job
            String jobId = "af7a26d6-cf0b-458c-a6ed-4b6318c74da3";

            CreateMonitorResponseDto monitor = client.monitors().createMonitor(
                CreateMonitorRequestDto.builder()
                    .referenceJobId(jobId)
                    .schedule("every day at 12 PM UTC")
                    .webhookIds(List.of("a1b2c3d4-e5f6-7890-abcd-ef1234567890"))
                    .build()
            );
            String monitorId = monitor.getMonitorId().orElseThrow();
            System.out.println("Monitor created: " + monitorId);

            // Update webhook
            client.monitors().updateMonitor(
                monitorId,
                UpdateMonitorRequestDto.builder()
                    .webhookIds(List.of("b2c3d4e5-f6a7-8901-bcde-f12345678901"))
                    .limit(100)
                    .build()
            );

            // List all monitors
            ListMonitorsResponseDto allMonitors = client.monitors().listMonitors();
            allMonitors.getMonitors().forEach(m -> {
                String status = m.getEnabled() ? "active" : "paused";
                System.out.println(String.format("%s: %s", m.getMonitorId(), status));
            });

            // Control execution
            client.monitors().disableMonitor(monitorId);
            client.monitors().enableMonitor(monitorId);

            // List execution history
            ListMonitorJobsResponse jobs = client.monitors().listMonitorJobs(
                monitorId,
                ListMonitorJobsRequest.builder().sort("desc").build()
            );
            System.out.println("\nMonitor executed " + jobs.getTotalJobs() + " jobs");
            jobs.getJobs().forEach(job -> {
                System.out.println(String.format(
                    "  Job %s: %s to %s",
                    job.getJobId(),
                    job.getStartDate(),
                    job.getEndDate()
                ));
            });

            // Get aggregated results
            PullMonitorResponseDto results = client.monitors().pullMonitorResults(monitorId);
            System.out.println("\nCollected " + results.getRecords().orElse(0) + " total records");
            results.getAllRecords().ifPresent(records ->
                records.forEach(record -> System.out.println("  " + record.getRecordTitle()))
            );

        } catch (NewscatcherApiApiException e) {
            System.err.println("Status: " + e.statusCode());
            System.err.println("Error: " + e.body());
        }
    }
}

Company watchlist

Company watchlist lets you track specific companies across jobs. Create entities, group them into a dataset, then connect the dataset to any job to get per-company relevance scores in results.

Create entity
Create dataset from CSV
Submit connected job
Read results

import com.newscatcher.catchall.CatchAllApi;
import com.newscatcher.catchall.types.AdditionalAttributes;
import com.newscatcher.catchall.types.CompanyAttributes;
import com.newscatcher.catchall.types.CreateEntityRequest;
import com.newscatcher.catchall.types.CreateEntityResponse;
import com.newscatcher.catchall.types.EntityType;
import java.util.List;

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .build();

CreateEntityResponse entity = client.entities().createEntity(
    CreateEntityRequest.builder()
        .name("NewsCatcher")
        .entityType(EntityType.COMPANY)
        .description("AI-powered news data provider")
        .additionalAttributes(AdditionalAttributes.builder()
            .companyAttributes(CompanyAttributes.builder()
                .domain("newscatcherapi.com")
                .alternativeNames(List.of("NC", "NewsCatcher API"))
                .keyPersons(List.of("Artem Bugara", "Maksym Sugonyaka"))
                .build())
            .build())
        .build()
);
String entityId = entity.getId();

Upload a CSV to create a dataset and entities in one step:

import com.newscatcher.catchall.resources.datasets.requests.CreateDatasetFromCsvRequest;
import com.newscatcher.catchall.types.CreateDatasetCsvResponse;
import java.io.File;

CreateDatasetCsvResponse dataset = client.datasets().createDatasetFromCsv(
    new File("companies.csv"),
    CreateDatasetFromCsvRequest.builder()
        .name("My Portfolio")
        .build()
);
String datasetId = dataset.getDatasetId();

CSV format:

name,description,domain,alternative_names,key_persons
NewsCatcher,"AI-powered news data provider",newscatcherapi.com,"NC;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"

Wait for the dataset to reach ready status, then submit a job:

import com.newscatcher.catchall.types.DatasetResponse;
import com.newscatcher.catchall.types.DatasetStatus;
import com.newscatcher.catchall.resources.jobs.requests.SubmitRequestDto;
import java.util.List;
import java.util.concurrent.TimeUnit;

// Poll until ready
while (true) {
    DatasetResponse status = client.datasets().getDataset(datasetId);
    if (DatasetStatus.READY.equals(status.getLatestStatus().orElse(null))) break;
    TimeUnit.SECONDS.sleep(5);
}

// Submit connected job
var job = client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("AI chip partnerships")
        .connectedDatasetIds(List.of(datasetId))
        .build()
);

Each record includes a connected_entities list with relevance scores:

import com.newscatcher.catchall.types.PullJobResponseDto;

PullJobResponseDto results = client.jobs().getJobResults(job.getJobId());

results.getAllRecords().forEach(record -> {
    System.out.println(record.getRecordTitle());
    record.getConnectedEntities().ifPresent(entities ->
        entities.forEach(entity -> {
            System.out.printf("  %s: score %.0f/10%n",
                entity.getName(), entity.getEdScore());
            System.out.println("  " + entity.getRelation());
        })
    );
});

For a full step-by-step walkthrough including batch entity creation and the JSON API path, see Company Watchlist.

Error handling

Handle API errors with structured exception handling:

import com.newscatcher.catchall.core.NewscatcherApiApiException;

try {
    client.jobs().createJob(
        SubmitRequestDto.builder()
            .query("AI company acquisitions")
            .build()
    );
} catch (NewscatcherApiApiException e) {
    System.err.println("Status: " + e.statusCode());
    System.err.println("Error: " + e.body());
}

Advanced usage

Pagination

Retrieve large result sets page by page:

import com.newscatcher.catchall.resources.jobs.requests.GetJobResultsRequest;

int page = 1;
while (true) {
    var results = client.jobs().getJobResults(
        jobId,
        GetJobResultsRequest.builder()
            .page(page)
            .pageSize(100)
            .build()
    );

    System.out.println("Page " + page + "/" + results.getTotalPages().orElse(1));

    results.getAllRecords().ifPresent(records ->
        records.forEach(record ->
            System.out.println("  " + record.getRecordTitle())
        )
    );

    if (results.getPage().orElse(0) >= results.getTotalPages().orElse(1)) {
        break;
    }
    page++;
}

Timeouts

Configure custom timeouts at client or request level:

Client-level
Request-level

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .timeout(30)
    .build();

import com.newscatcher.catchall.core.RequestOptions;

client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("AI company acquisitions")
        .build(),
    RequestOptions.builder()
        .timeout(10)
        .build()
);

Retries

Configure automatic retry behavior for failed requests:

Client-level
Request-level

CatchAllApi client = CatchAllApi.builder()
    .apiKey("YOUR_API_KEY")
    .maxRetries(3)
    .build();

client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("AI company acquisitions")
        .build(),
    RequestOptions.builder()
        .maxRetries(3)
        .build()
);

Get started

Concepts

How to

API Reference

Libraries

Integrations

Installation

Quickstart

Working with jobs

Working with monitors

Company watchlist

Error handling

Advanced usage

Timeouts

Retries

Resources

​Installation

​Quickstart

​Working with jobs

​Working with monitors

​Company watchlist

​Error handling

​Advanced usage

​Pagination

​Timeouts

​Retries

​Resources

Installation

Quickstart

Working with jobs

Working with monitors

Company watchlist

Error handling

Advanced usage

Pagination

Timeouts

Retries

Resources