reference.md

Reference

Jobs

client.jobs.getUserJobs() -> ListUserJobsResponseDto

📝 Description

Returns all jobs created by the authenticated user.

🔌 Usage

client.jobs().getUserJobs(
    GetUserJobsRequest
        .builder()
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

search: Optional<String> — Filter results by text (case-insensitive substring match).

ownership: Optional<OwnershipFilter>

projectId: Optional<String> — Filter results to resources belonging to this project.

mode: Optional<GetUserJobsRequestMode> — Filter results by processing mode. Returns only jobs that ran in the specified mode.

client.jobs.validateQuery(request) -> ValidateQueryResponseDto

📝 Description

Checks whether a query is well-formed and likely to produce good results before submitting a job.

Returns a quality assessment with a status level, identified issues, and actionable suggestions.

🔌 Usage

client.jobs().validateQuery(
    ValidateQueryRequestDto
        .builder()
        .query("Series B funding rounds for SaaS startups")
        .build()
);

⚙️ Parameters

query: String — Plain text query to validate.

client.jobs.initialize(request) -> InitializeResponseDto

📝 Description

Get suggested validators, enrichments, and date ranges for a query.

🔌 Usage

client.jobs().initialize(
    InitializeRequestDto
        .builder()
        .query("Series B funding rounds for SaaS startups")
        .context("Focus on funding amount and company name")
        .build()
);

⚙️ Parameters

query: String

context: Optional<String>

connectedDatasetIds: Optional<List<String>> — Optional list of watchlist dataset IDs connected to this job.

fetchAllWatchlistNews: Optional<Boolean>

When true, returns generic news validators and enrichments suitable for watchlist-based article collection instead of query-specific fields.

client.jobs.createJob(request) -> SubmitResponseDto

📝 Description

Submit a query to create a new processing job.

🔌 Usage

client.jobs().createJob(
    SubmitRequestDto
        .builder()
        .query("Series B funding rounds for SaaS startups")
        .context("Focus on funding amount and company name")
        .limit(10)
        .startDate(OffsetDateTime.parse("2026-02-18T00:00:00Z"))
        .endDate(OffsetDateTime.parse("2026-02-23T00:00:00Z"))
        .mode(SubmitRequestDtoMode.BASE)
        .build()
);

⚙️ Parameters

query: String

context: Optional<String>

limit: Optional<Integer>

startDate: Optional<OffsetDateTime>

endDate: Optional<OffsetDateTime>

validators: Optional<List<ValidatorSchema>>

Custom validators for filtering web page clusters.

If not provided, validators are generated automatically based on the query. The system may also inject validators during the analyzing stage — for example, converting a relative time qualifier into an explicit event-date gate. The returned validators[] in the job status shows the complete applied set, including any system-added ones.

enrichments: Optional<List<EnrichmentSchema>>

Custom enrichment fields for data extraction.

If not provided, enrichments are generated automatically based on the query.

mode: Optional<SubmitRequestDtoMode>

Job processing mode.

• base: Full pipeline with validation and enrichment.
• lite: Lightweight extraction with faster processing. Returns titles and citations only.

connectedDatasetIds: Optional<List<String>>

Dataset IDs to connect to the job. When provided, this enables Company Monitors mode — the job returns only events relevant to companies in the connected datasets. To set the minimum relevance threshold, use ed_score_min.

The dataset must have latest_status: ready before the job is submitted. Submitting with a non-existent or inaccessible dataset ID returns 400.

edScoreMin: Optional<Integer>

The minimum relevance score a connected entity must reach for its record to be included in results.

Only valid when connected_dataset_ids is set; otherwise ignored. Records where no connected entity meets the threshold are excluded entirely.

projectId: Optional<String> — Project to assign this job to. The job appears in the project's resource list immediately after submission.

webhookIds: Optional<List<String>> — IDs of webhooks to notify when the job completes. Maximum 5 per job.

fetchAllWatchlistNews: Optional<Boolean>

When true, retrieves all news for connected Company Monitors entities without topic filtering. Requires connected_dataset_ids to be set.

edAssociationType: Optional<EntityAssociationType>

Filter events by entity association type. event_associated keeps only events where the entity is a direct actor. mention keeps only events where the entity is merely referenced. Only relevant when connected_dataset_ids is set.

sourceGroups: Optional<List<String>>

Slugs of source groups to scope fetching to their curated domain allowlists.

Source groups are named domain lists maintained by NewsCatcher (for example "Top 100 US Finance"). Retrieve the groups available to your organization with List source groups.

Domains are resolved when the job runs, so a group's current membership always applies. Maximum 20 groups per job. An unknown or inaccessible slug is rejected at submit time.

client.jobs.getJobStatus(jobId) -> StatusResponseDto

📝 Description

Retrieve the current processing status of a job.

🔌 Usage

client.jobs().getJobStatus(
    "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    GetJobStatusRequest
        .builder()
        .build()
);

⚙️ Parameters

jobId: String — Unique job identifier returned from POST /catchAll/submit.

client.jobs.getJobResults(jobId) -> PullJobResponseDto

📝 Description

Retrieve the final results for a completed job.

🔌 Usage

client.jobs().getJobResults(
    "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    GetJobResultsRequest
        .builder()
        .build()
);

⚙️ Parameters

jobId: String — Unique job identifier returned from POST /catchAll/submit.

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

client.jobs.getJobResultsCsv(jobId) -> String

📝 Description

Returns a completed job's result records as a CSV download. One row per record, with enrichment fields as columns and citations as a JSON column.

If the job used connected entity datasets, connected entities are split into event_associated_entities and mention_entities JSON columns. When no entity dataset was used, those two columns are omitted from the export entirely.

🔌 Usage

client.jobs().getJobResultsCsv(
    "job_id",
    GetJobResultsCsvRequest
        .builder()
        .build()
);

⚙️ Parameters

jobId: String — Unique job identifier returned from POST /catchAll/submit.

client.jobs.continueJob(request) -> ContinueResponseDto

📝 Description

Continue an existing job to process more records beyond the initial limit.

🔌 Usage

client.jobs().continueJob(
    ContinueRequestDto
        .builder()
        .jobId("5f0c9087-85cb-4917-b3c7-e5a5eff73a0c")
        .newLimit(100)
        .build()
);

⚙️ Parameters

jobId: String — Job identifier of the completed job to continue.

newLimit: Optional<Integer> — New record limit for continued processing. Must be greater than the previous limit. If not provided, defaults to the plan maximum.

client.jobs.deleteJob(jobId) -> DeleteJobResponseDto

📝 Description

Soft-deletes a job. The job is flagged as deleted and no longer appears in list results. The underlying data is retained.

Only the job owner can delete a job. Returns 404 if the job is not found or does not belong to the authenticated user.

Deleting an already-deleted job returns 200.

🔌 Usage

client.jobs().deleteJob(
    "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    DeleteJobRequest
        .builder()
        .build()
);

⚙️ Parameters

jobId: String — Unique job identifier returned from POST /catchAll/submit.

client.jobs.listSourceGroups() -> ListSourceGroupsResponseDto

📝 Description

Returns a paginated list of source groups visible to your organization.

A source group is a named, curated domain allowlist maintained by NewsCatcher — for example "Top 100 US Finance". Pass a group's slug in source_groups when creating a job to scope article fetching to that group's domains, instead of maintaining a long domain list yourself.

The response covers public groups plus any restricted groups your organization has been granted access to. Each entry returns slug, name, and description.

🔌 Usage

client.jobs().listSourceGroups(
    ListSourceGroupsRequest
        .builder()
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of source groups per page.

Event Monitors

client.eventMonitors.listMonitors() -> ListMonitorsResponseDto

📝 Description

Returns all event monitors created by the authenticated user.

🔌 Usage

client.eventMonitors().listMonitors(
    ListMonitorsRequest
        .builder()
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

search: Optional<String> — Filter results by text (case-insensitive substring match).

ownership: Optional<OwnershipFilter>

projectId: Optional<String> — Filter results to resources belonging to this project.

client.eventMonitors.createMonitor(request) -> CreateMonitorResponseDto

📝 Description

Create a scheduled event monitor based on a reference job.

🔌 Usage

client.eventMonitors().createMonitor(
    CreateMonitorRequestDto
        .builder()
        .referenceJobId("5f0c9087-85cb-4917-b3c7-e5a5eff73a0c")
        .schedule("every day at 12 PM")
        .timezone("UTC")
        .webhookIds(
            Optional.of(
                Arrays.asList("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
            )
        )
        .limit(10)
        .backfill(true)
        .build()
);

⚙️ Parameters

referenceJobId: String

Job ID to use as template for scheduled runs. Defines the query, validators, and enrichments used for each scheduled run.

If backfill is true, the job's end_date must be within the last 7 days.

schedule: String — Event monitor schedule in plain text format. Minimum frequency depends on your plan.

timezone: Optional<String>

The IANA timezone identifier used as the fallback when the schedule string does not include an explicit timezone.

If the schedule includes a timezone abbreviation (for example, "every day at 9am EST"), the parsed timezone takes priority and this value is ignored.

webhookIds: Optional<List<String>>

IDs of centralized webhooks to notify on each run completion. Passing IDs here is equivalent to calling POST /catchAll/webhooks/{webhook_id}/resources for each ID after creation. Maximum 5 per event monitor.

limit: Optional<Integer> — Maximum number of records per event monitor run. If not provided, defaults to the plan limit.

backfill: Optional<Boolean>

If true, fills the data gap between the reference job's end_date and the first scheduled run. The reference job's end_date must be within the last 7 days.

If false, no gap filling occurs and the first run uses the current cron window only — the reference job's age does not matter.

projectId: Optional<String> — Project to assign this event monitor to. The event monitor appears in the project's resource list after creation.

client.eventMonitors.pullMonitorResults(monitorId) -> PullMonitorResponseDto

📝 Description

Retrieve aggregated results from all jobs executed by an event monitor.

🔌 Usage

client.eventMonitors().pullMonitorResults(
    "monitor_id",
    PullMonitorResultsRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

client.eventMonitors.pullMonitorResultsCsv(monitorId) -> String

📝 Description

Returns the most recent run's records as a CSV download. One row per record, with enrichment fields as columns and citations as a JSON column.

If the event monitor's reference job used connected entity datasets, connected entities are split into event_associated_entities and mention_entities JSON columns. When no entity dataset was used, those two columns are omitted from the export entirely.

🔌 Usage

client.eventMonitors().pullMonitorResultsCsv(
    "monitor_id",
    PullMonitorResultsCsvRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

client.eventMonitors.listMonitorJobs(monitorId) -> ListMonitorJobsResponse

📝 Description

Return all jobs executed by an event monitor.

🔌 Usage

client.eventMonitors().listMonitorJobs(
    "monitor_id",
    ListMonitorJobsRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

sort: Optional<ListMonitorJobsRequestSort> — Sort by start_date (asc or desc).

client.eventMonitors.getMonitorStatusHistory(monitorId) -> MonitorStatusHistoryResponseDto

📝 Description

Returns the full execution history of an event monitor as a list of status entries, ordered from newest to oldest.

🔌 Usage

client.eventMonitors().getMonitorStatusHistory(
    "monitor_id",
    GetMonitorStatusHistoryRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

client.eventMonitors.enableMonitor(monitorId, request) -> EnableMonitorResponse

📝 Description

Resume scheduled job execution for an event monitor.

🔌 Usage

client.eventMonitors().enableMonitor(
    "monitor_id",
    EnableMonitorRequestDto
        .builder()
        .backfill(true)
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

backfill: Optional<Boolean>

If true, fills the data gap between the last job's end_date and the first scheduled run after enabling. The last job's end_date must be within the last 7 days.

If false, no gap filling occurs and the first run uses the current cron window only — the last job's age does not matter.

client.eventMonitors.disableMonitor(monitorId) -> DisableMonitorResponse

📝 Description

Stop scheduled job execution for an event monitor.

🔌 Usage

client.eventMonitors().disableMonitor(
    "monitor_id",
    DisableMonitorRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

client.eventMonitors.deleteMonitor(monitorId) -> DeleteMonitorResponseDto

📝 Description

Soft-deletes an event monitor. The event monitor is flagged as deleted, stops executing scheduled jobs immediately, and no longer appears in list results.

Only the event monitor owner can delete an event monitor. Returns 404 if the event monitor is not found or does not belong to the authenticated user.

Deleting an already-deleted event monitor returns 200.

🔌 Usage

client.eventMonitors().deleteMonitor(
    "monitor_id",
    DeleteMonitorRequest
        .builder()
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

client.eventMonitors.updateMonitor(monitorId, request) -> UpdateMonitorResponseDto

📝 Description

Update the webhook assignments, record limit, or schedule of an existing event monitor. Omitted fields are left unchanged.

Passing schedule replaces the event monitor's current schedule. The new schedule takes effect from the next scheduler reload, and the old schedule stops firing. The reference job cannot be changed.

🔌 Usage

client.eventMonitors().updateMonitor(
    "monitor_id",
    UpdateMonitorRequestDto
        .builder()
        .webhookIds(
            Optional.of(
                Arrays.asList("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
            )
        )
        .build()
);

⚙️ Parameters

monitorId: String — Event monitor identifier.

webhookIds: Optional<List<String>>

Updated list of centralized webhook IDs for this event monitor.

Replaces all existing webhook assignments. Pass an empty array [] to clear all assignments. Omit to leave existing assignments unchanged.

limit: Optional<Integer> — Updated maximum number of records per event monitor run.

schedule: Optional<String>

New natural-language schedule that replaces the event monitor's current schedule. Examples: every day at 9 AM, every Monday at 6 PM EST.

Omit to keep the current schedule. The new schedule takes effect from the next scheduler reload, and the old schedule stops firing. Returns 422 if the text can't be parsed or runs would be spaced too closely.

timezone: Optional<String>

IANA timezone for the new schedule (for example, America/New_York). A timezone included in the schedule text takes precedence. Ignored if schedule is not set.

Webhooks

client.webhooks.listWebhooks() -> ListWebhooksResponseDto

📝 Description

Returns a paginated list of webhooks belonging to the organization.

🔌 Usage

client.webhooks().listWebhooks(
    ListWebhooksRequest
        .builder()
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of webhooks per page.

search: Optional<String> — Filter results by text (case-insensitive substring match).

projectId: Optional<String> — Filter results to resources belonging to this project.

client.webhooks.createWebhook(request) -> CreateWebhookResponseDto

📝 Description

Creates a new webhook endpoint for the organization.

Optionally pass project_id to attach the webhook to a project in the same request.

🔌 Usage

client.webhooks().createWebhook(
    CreateWebhookRequestDto
        .builder()
        .name("Layoffs Alert")
        .url("https://hooks.slack.com/services/T000/B000/xxx")
        .type(WebhookType.SLACK)
        .deliveryMode(DeliveryMode.FULL)
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

name: String — Human-readable label for this webhook.

url: String

Destination URL that receives the payload. Must use HTTPS. IP addresses are not accepted.

Type-specific URL requirements:

• slack: Must start with https://hooks.slack.com/.
• teams: Hostname must match *.webhook.office.com or *.webhook.office365.com.
• generic: Any valid HTTPS domain.
• custom: Any valid HTTPS domain.

When type is omitted, it is auto-detected from the URL.

type: Optional<WebhookType>

deliveryMode: Optional<DeliveryMode>

method: Optional<HttpMethod>

headers: Optional<Map<String, String>> — Custom HTTP headers forwarded with each delivery.

params: Optional<Map<String, String>> — Query parameters appended to the webhook URL.

auth: Optional<CreateWebhookRequestDtoAuth>

Authentication forwarded with each delivery. Supported types:

• bearer: Adds an Authorization: Bearer <token> header.
• api_key: Adds a custom header with the specified name and value.
• basic: Adds an Authorization: Basic <credentials> header.

formatterConfig: Optional<FormatterConfigDto> — Custom payload formatter. Required when type is custom.

projectId: Optional<String>

Optional project to attach this webhook to at creation time. Equivalent to creating the webhook and then calling POST /catchAll/projects/{project_id}/resources with resource_type: webhook.

The project must belong to your organization.

client.webhooks.getWebhook(webhookId) -> GetWebhookResponseDto

📝 Description

Returns the full configuration of a single webhook by ID.

🔌 Usage

client.webhooks().getWebhook(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    GetWebhookRequest
        .builder()
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

client.webhooks.deleteWebhook(webhookId)

📝 Description

Permanently deletes a webhook and removes all resource assignments.

Assigned jobs and event monitors no longer trigger delivery to this webhook. This operation cannot be undone.

🔌 Usage

client.webhooks().deleteWebhook(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    DeleteWebhookRequest
        .builder()
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

client.webhooks.updateWebhook(webhookId, request) -> UpdateWebhookResponseDto

📝 Description

Updates one or more fields of an existing webhook.

🔌 Usage

client.webhooks().updateWebhook(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    UpdateWebhookRequestDto
        .builder()
        .name("Layoffs Alert (EU)")
        .isActive(false)
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

name: Optional<String> — Updated webhook name.

url: Optional<String> — Updated destination URL. Must use HTTPS. Type-specific URL rules apply.

type: Optional<WebhookType>

deliveryMode: Optional<DeliveryMode>

method: Optional<HttpMethod>

headers: Optional<Map<String, String>> — Updated HTTP headers. Replaces existing headers entirely.

params: Optional<Map<String, String>> — Updated query parameters. Replaces existing params entirely.

auth: Optional<UpdateWebhookRequestDtoAuth> — Updated authentication configuration. Replaces existing auth entirely.

formatterConfig: Optional<FormatterConfigDto> — Updated custom payload formatter. Set only when type is custom.

isActive: Optional<Boolean> — Set to false to disable delivery without deleting the webhook.

client.webhooks.testWebhook(webhookId, request) -> TestWebhookResponseDto

📝 Description

Sends a test HTTP request to the webhook URL using the webhook's configured method, headers, and auth. Returns the response from the target endpoint.

Use this to verify URL reachability and authentication before attaching the webhook to a live job or event monitor.

🔌 Usage

client.webhooks().testWebhook(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    TestWebhookRequestDto
        .builder()
        .payload(
            new HashMap<String, Object>() {{
                put("test", true);
                put("message", "CatchAll webhook test");
            }}
        )
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

payload: Optional<Map<String, Object>>

Custom payload to send in the test request. If omitted, a synthetic test payload is sent.

client.webhooks.listWebhookResources(webhookId) -> ListWebhookResourcesResponseDto

📝 Description

Returns a paginated list of resources currently assigned to this webhook.

🔌 Usage

client.webhooks().listWebhookResources(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    ListWebhookResourcesRequest
        .builder()
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

resourceType: Optional<MappableResourceType>

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of assignments per page.

client.webhooks.assignWebhookResource(webhookId, request) -> AssignWebhookResourceResponseDto

📝 Description

Attaches a job, event monitor, or event monitor group to the webhook. When the resource completes, the webhook receives a delivery.

A single webhook can be assigned to multiple resources. Each resource can have up to 5 webhooks assigned.

🔌 Usage

client.webhooks().assignWebhookResource(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    AssignWebhookResourceRequestDto
        .builder()
        .resourceType(MappableResourceType.MONITOR)
        .resourceId("3fec5b07-8786-46d7-9486-d43ff67eccd4")
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

resourceType: MappableResourceType — Type of resource to assign.

resourceId: String — ID of the resource to assign.

client.webhooks.removeWebhookResource(webhookId, resourceType, resourceId)

📝 Description

Detaches a resource from this webhook. Completions of the resource no longer trigger delivery to this webhook.

The webhook and the resource itself are not deleted.

🔌 Usage

client.webhooks().removeWebhookResource(
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    MappableResourceType.JOB,
    "3fec5b07-8786-46d7-9486-d43ff67eccd4",
    RemoveWebhookResourceRequest
        .builder()
        .build()
);

⚙️ Parameters

webhookId: String — Unique webhook identifier.

resourceType: MappableResourceType

resourceId: String — Unique resource identifier.

client.webhooks.listWebhooksForResource(resourceType, resourceId) -> ListWebhooksResponseDto

📝 Description

Returns all webhooks currently assigned to the given resource.

🔌 Usage

client.webhooks().listWebhooksForResource(
    MappableResourceType.JOB,
    "3fec5b07-8786-46d7-9486-d43ff67eccd4",
    ListWebhooksForResourceRequest
        .builder()
        .build()
);

⚙️ Parameters

resourceType: MappableResourceType

resourceId: String — Unique resource identifier.

isActive: Optional<Boolean> — Filter by active status. Omit to return webhooks regardless of status.

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of webhooks per page.

client.webhooks.triggerWebhook(resourceType, resourceId)

📝 Description

Manually dispatches a webhook delivery for a resource on demand, without waiting for the next job or event monitor cycle.

Use this to re-deliver results after a failed delivery, replay a specific job's results, or validate a webhook against live data. The webhook must already be assigned to the resource.

🔌 Usage

client.webhooks().triggerWebhook(
    MappableResourceType.JOB,
    "3fec5b07-8786-46d7-9486-d43ff67eccd4",
    TriggerWebhookRequest
        .builder()
        .webhookId("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
        .jobId("3fec5b07-8786-46d7-9486-d43ff67eccd4")
        .build()
);

⚙️ Parameters

resourceType: MappableResourceType

resourceId: String — Unique resource identifier.

webhookId: String — Identifier of the webhook to trigger. Must be assigned to the resource.

jobId: Optional<String>

Specific job run to deliver. Optional for job resources; for monitor and monitor_group resources, selects a past run to replay. When omitted, the latest available results are delivered.

client.webhooks.getWebhookDeliveryHistory() -> DeliveryHistoryResponseDto

📝 Description

Returns a paginated delivery log for a given resource, ordered by timestamp descending.

Each record shows the webhook dispatched, the HTTP status code returned, delivery outcome, and any error or warning messages. Use this to debug failed deliveries or audit dispatch activity.

🔌 Usage

client.webhooks().getWebhookDeliveryHistory(
    GetWebhookDeliveryHistoryRequest
        .builder()
        .resourceType(MappableResourceType.JOB)
        .resourceId("3fec5b07-8786-46d7-9486-d43ff67eccd4")
        .build()
);

⚙️ Parameters

resourceType: MappableResourceType — Type of the resource to retrieve delivery history for.

resourceId: String — Identifier of the resource to retrieve delivery history for.

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

Entities

client.entities.listEntities() -> EntityListResponse

📝 Description

Returns a paginated list of entities belonging to the authenticated organization. Supports filtering by status and entity type, and sorting by name, status, or creation date.

🔌 Usage

client.entities().listEntities(
    ListEntitiesRequest
        .builder()
        .search("NewsCatcher")
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of entities per page.

search: Optional<String> — Filter entities by name (case-insensitive substring match).

status: Optional<EntityStatus>

entityType: Optional<EntityType>

sortBy: Optional<EntitySortBy>

sortOrder: Optional<SortOrder>

projectId: Optional<String> — Filter results to resources belonging to this project.

client.entities.createEntity(request) -> CreateEntityResponse

📝 Description

Creates a new company entity and begins background enrichment.

Each entity requires a name plus at least one of: a description or a domain. Providing both is recommended — domain is the highest-signal identifier because it is unambiguous; a well-written description is the best alternative when no domain is available.

The entity status starts as pending and transitions to ready once enrichment completes.

🔌 Usage

client.entities().createEntity(
    CreateEntityRequest
        .builder()
        .name("NewsCatcher")
        .entityType(EntityType.COMPANY)
        .description("NewsCatcher is a data-as-a-service company providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).")
        .additionalAttributes(
            AdditionalAttributes
                .builder()
                .companyAttributes(
                    CompanyAttributes
                        .builder()
                        .domain("newscatcherapi.com")
                        .keyPersons(
                            Optional.of(
                                Arrays.asList("Artem Bugara", "Maksym Sugonyaka")
                            )
                        )
                        .alternativeNames(
                            Optional.of(
                                Arrays.asList("NewsCatcher CatchAll", "NewsCatcher API")
                            )
                        )
                        .build()
                )
                .build()
        )
        .build()
);

⚙️ Parameters

request: CreateEntityRequest

client.entities.createEntitiesBatch(request) -> CreateEntitiesBatchResponse

📝 Description

Creates multiple entities in a single request. Each entity is processed independently — a failure in one does not affect others.

Each entity requires a name plus at least one of: a description or a domain. See Create entity for the full field reference.

Returns an array of {id, status} objects in the same order as the input array.

🔌 Usage

client.entities().createEntitiesBatch(
    CreateEntitiesBatchRequest
        .builder()
        .entities(
            Arrays.asList(
                CreateEntityRequest
                    .builder()
                    .name("OpenAI")
                    .entityType(EntityType.COMPANY)
                    .description("Artificial intelligence research company")
                    .additionalAttributes(
                        AdditionalAttributes
                            .builder()
                            .companyAttributes(
                                CompanyAttributes
                                    .builder()
                                    .domain("openai.com")
                                    .keyPersons(
                                        Optional.of(
                                            Arrays.asList("Sam Altman")
                                        )
                                    )
                                    .alternativeNames(
                                        Optional.of(
                                            Arrays.asList("Open AI")
                                        )
                                    )
                                    .build()
                            )
                            .build()
                    )
                    .build(),
                CreateEntityRequest
                    .builder()
                    .name("Stripe")
                    .entityType(EntityType.COMPANY)
                    .description("Online payment processing platform")
                    .additionalAttributes(
                        AdditionalAttributes
                            .builder()
                            .companyAttributes(
                                CompanyAttributes
                                    .builder()
                                    .domain("stripe.com")
                                    .keyPersons(
                                        Optional.of(
                                            Arrays.asList("Patrick Collison", "John Collison")
                                        )
                                    )
                                    .build()
                            )
                            .build()
                    )
                    .build()
            )
        )
        .build()
);

⚙️ Parameters

entities: List<CreateEntityRequest>

Array of entities to create. Each item follows the same schema as single entity creation.

client.entities.getEntity(entityId) -> EntityResponse

📝 Description

Returns a single entity by ID with all attributes and current status.

🔌 Usage

client.entities().getEntity(
    "854198fa-f702-49db-a381-0427fa87f173",
    GetEntityRequest
        .builder()
        .build()
);

⚙️ Parameters

entityId: String — Unique entity identifier.

client.entities.deleteEntity(entityId)

📝 Description

Permanently deletes an entity. The entity is removed from all datasets and the search index. This operation cannot be undone.

🔌 Usage

client.entities().deleteEntity(
    "854198fa-f702-49db-a381-0427fa87f173",
    DeleteEntityRequest
        .builder()
        .build()
);

⚙️ Parameters

entityId: String — Unique entity identifier.

client.entities.updateEntity(entityId, request) -> EntityResponse

📝 Description

Updates one or more fields of an existing entity.

🔌 Usage

client.entities().updateEntity(
    "854198fa-f702-49db-a381-0427fa87f173",
    UpdateEntityRequest
        .builder()
        .description("Updated description")
        .additionalAttributes(
            AdditionalAttributes
                .builder()
                .companyAttributes(
                    CompanyAttributes
                        .builder()
                        .alternativeNames(
                            Optional.of(
                                Arrays.asList("NewsCatcher CatchAll", "NewsCatcher API", "NCA")
                            )
                        )
                        .build()
                )
                .build()
        )
        .build()
);

⚙️ Parameters

entityId: String — Unique entity identifier.

name: Optional<String> — Updated entity name.

description: Optional<String> — Updated description.

externalEntityId: Optional<String> — Updated external identifier for this entity.

additionalAttributes: Optional<AdditionalAttributes>

Datasets

client.datasets.listDatasets() -> DatasetListResponse

📝 Description

Returns a paginated list of datasets belonging to the authenticated organization. Supports filtering by status and sorting by name, status, or creation date.

🔌 Usage

client.datasets().listDatasets(
    ListDatasetsRequest
        .builder()
        .search("Portfolio")
        .projectId("60a85db4-78ec-4b78-876a-bc7d9cdadd04")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of datasets per page.

search: Optional<String> — Filter datasets by name (case-insensitive substring match).

latestStatus: Optional<DatasetStatus> — Filter by dataset status.

sortBy: Optional<DatasetSortBy>

sortOrder: Optional<SortOrder>

ownership: Optional<OwnershipFilter>

projectId: Optional<String> — Filter results to resources belonging to this project.

client.datasets.createDataset(request) -> DatasetResponse

📝 Description

Creates a new dataset from a list of existing entity IDs. The optional description field here describes the dataset itself — it is separate from the entity-level description used for matching.

Entities must be created before adding them to a dataset. Each entity requires a name plus at least one of: a description or a domain. Use Create entity or Create entities batch to create entities first.

If any of the provided entity IDs do not exist or do not belong to your organization, the request fails with 400. All entity IDs must be valid before the dataset is created.

To create a dataset and entities in one step, use the Create dataset from CSV endpoint instead.

🔌 Usage

client.datasets().createDataset(
    CreateDatasetRequest
        .builder()
        .name("My Portfolio")
        .description("Companies in our investment portfolio")
        .entityIds(
            Optional.of(
                Arrays.asList("854198fa-f702-49db-a381-0427fa87f173", "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
            )
        )
        .build()
);

⚙️ Parameters

name: String — Name for the dataset.

description: Optional<String> — Optional description.

entityIds: Optional<List<String>> — IDs of existing entities to include in the dataset. All IDs must belong to the authenticated organization. If any ID is invalid or not found, the request fails with 400.

client.datasets.createDatasetFromCsv(request) -> CreateDatasetCsvResponse

📝 Description

Creates a new dataset by uploading a CSV file. Each row in the CSV becomes an entity. Each row requires a name plus at least one of: a description or a domain; all other columns are optional. Note: description in the CSV is the entity's matching description — it is separate from the dataset-level description field in the form data.

CSV format:

name,description,domain,alternative_names,key_persons
NewsCatcher,"NewsCatcher is a data-as-a-service company providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",newscatcherapi.com,"NewsCatcher CatchAll;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"

Use semicolons (;) to separate multiple values in alternative_names and key_persons. Rows with empty name are skipped and reported in validation_report.

Note: The response shape differs from the JSON dataset creation endpoint: it returns dataset_id (not id) and includes a validation_report with details on skipped rows.

🔌 Usage

client.datasets().createDatasetFromCsv(
    null,
    CreateDatasetFromCsvRequest
        .builder()
        .name("name")
        .build()
);

client.datasets.getDataset(datasetId) -> DatasetResponse

📝 Description

Returns a single dataset by ID including entity count and current status.

🔌 Usage

client.datasets().getDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    GetDatasetRequest
        .builder()
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

client.datasets.deleteDataset(datasetId)

📝 Description

Permanently deletes a dataset. The entities within the dataset are not deleted — only the dataset itself. This operation cannot be undone.

🔌 Usage

client.datasets().deleteDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    DeleteDatasetRequest
        .builder()
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

client.datasets.updateDataset(datasetId, request) -> DatasetResponse

📝 Description

Updates the name or description of a dataset.

🔌 Usage

client.datasets().updateDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    UpdateDatasetRequest
        .builder()
        .name("My Portfolio (updated)")
        .description("Updated Q1 2026 watchlist")
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

name: Optional<String> — Updated dataset name.

description: Optional<String> — Updated description.

client.datasets.addEntitiesToDataset(datasetId, request) -> ManageEntitiesResponse

📝 Description

Adds one or more existing entities to a dataset. Returns the number of entities added.

🔌 Usage

client.datasets().addEntitiesToDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    AddEntitiesToDatasetRequest
        .builder()
        .body(
            DatasetEntityIdsRequest
                .builder()
                .entityIds(
                    Arrays.asList("854198fa-f702-49db-a381-0427fa87f173")
                )
                .build()
        )
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

request: DatasetEntityIdsRequest

client.datasets.removeEntitiesFromDataset(datasetId, request) -> ManageEntitiesResponse

📝 Description

Removes one or more entities from a dataset. The entities themselves are not deleted — they are only removed from this dataset. Returns the number of entities removed.

🔌 Usage

client.datasets().removeEntitiesFromDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    RemoveEntitiesFromDatasetRequest
        .builder()
        .body(
            DatasetEntityIdsRequest
                .builder()
                .entityIds(
                    Arrays.asList("854198fa-f702-49db-a381-0427fa87f173")
                )
                .build()
        )
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

request: DatasetEntityIdsRequest

client.datasets.listEntitiesInDataset(datasetId, request) -> DatasetEntityListResponse

📝 Description

Returns a paginated list of entities in a dataset. Supports filtering by status, entity type, and name search.

🔌 Usage

client.datasets().listEntitiesInDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    ListDatasetEntitiesRequest
        .builder()
        .page(1)
        .pageSize(100)
        .search("OpenAI")
        .status(EntityStatus.READY)
        .entityType(EntityType.COMPANY)
        .sortBy(EntitySortBy.CREATED_AT)
        .sortOrder(SortOrder.DESC)
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

page: Optional<Integer> — The page number to retrieve.

pageSize: Optional<Integer> — The number of entities per page.

search: Optional<String> — Filters entities by name using a case-insensitive substring match.

status: Optional<EntityStatus>

entityType: Optional<EntityType>

sortBy: Optional<EntitySortBy>

sortOrder: Optional<SortOrder>

client.datasets.getDatasetStatusHistory(datasetId) -> DatasetStatusHistoryResponse

📝 Description

Returns the full status change history for a dataset, ordered chronologically from oldest to newest.

🔌 Usage

client.datasets().getDatasetStatusHistory(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    GetDatasetStatusHistoryRequest
        .builder()
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

client.datasets.uploadCsvToDataset(datasetId, request) -> UploadCsvToDatasetResponse

📝 Description

Appends new companies to an existing dataset by uploading a CSV file. Uses the same CSV format as the dataset creation endpoint.

The response omits dataset_name compared to the create-from-CSV endpoint since the dataset already exists.

🔌 Usage

client.datasets().uploadCsvToDataset(
    "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    null,
    UploadCsvToDatasetRequest
        .builder()
        .build()
);

⚙️ Parameters

datasetId: String — Unique dataset identifier.

Projects

client.projects.listProjects() -> ProjectListResponseDto

📝 Description

Returns all projects visible to the authenticated user.

🔌 Usage

client.projects().listProjects(
    ListProjectsRequest
        .builder()
        .search("M&A")
        .build()
);

⚙️ Parameters

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

search: Optional<String> — Filter by project name (case-insensitive substring match).

ownership: Optional<OwnershipFilter>

client.projects.createProject(request) -> CreateProjectResponseDto

📝 Description

Creates a new project.

🔌 Usage

client.projects().createProject(
    CreateProjectRequestDto
        .builder()
        .name("AI M&A Tracking")
        .description("Tracks AI-related M&A activity for our investment team.")
        .build()
);

⚙️ Parameters

name: String — Name for the project.

description: Optional<String> — Optional description.

client.projects.getProject(projectId) -> ProjectResponseDto

📝 Description

Returns a single project by ID.

🔌 Usage

client.projects().getProject(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    GetProjectRequest
        .builder()
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

client.projects.deleteProject(projectId)

📝 Description

Deletes a project. By default, assigned resources are unassigned but not deleted.

Webhooks are an exception: they are never deleted by this operation, even when delete_resources is true. Any attached webhook is detached from the project and continues to exist and deliver, because the same webhook may be attached to other projects.

🔌 Usage

client.projects().deleteProject(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    DeleteProjectRequest
        .builder()
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

deleteResources: Optional<Boolean>

If true, permanently deletes all resources (jobs, event monitors, datasets, event monitor groups) assigned to the project. If false, the project is deleted and its resources are unassigned but not deleted.

Webhooks are never deleted by either setting — they are only detached from the project.

client.projects.updateProject(projectId, request) -> UpdateProjectResponseDto

📝 Description

Updates the name or description of an existing project.

🔌 Usage

client.projects().updateProject(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    UpdateProjectRequestDto
        .builder()
        .name("AI M&A Tracking (Q2 2026)")
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

name: Optional<String> — New name for the project.

description: Optional<String> — New description for the project.

client.projects.getProjectOverview(projectId) -> ProjectOverviewResponseDto

📝 Description

Returns resource counts for a project, grouped by type and status.

For jobs and monitors, counts are broken down by status (for example, completed, failed). For datasets, monitor_groups, and webhooks, only a total count is returned.

🔌 Usage

client.projects().getProjectOverview(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    GetProjectOverviewRequest
        .builder()
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

client.projects.listProjectResources(projectId) -> ProjectResourceListResponseDto

📝 Description

Returns all resources assigned to a project, with optional filtering by type.

🔌 Usage

client.projects().listProjectResources(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    ListProjectResourcesRequest
        .builder()
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

resourceType: Optional<ProjectResourceType>

page: Optional<Integer> — Page number to retrieve.

pageSize: Optional<Integer> — Number of records per page.

client.projects.addResourceToProject(projectId, request) -> AddResourceResponseDto

📝 Description

Assigns one or more existing resources to a project in a single request.

🔌 Usage

client.projects().addResourceToProject(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    AddResourceRequestDto
        .builder()
        .resources(
            Arrays.asList(
                ResourceItemDto
                    .builder()
                    .resourceType(ProjectResourceType.JOB)
                    .resourceId("48421e16-1f50-4048-b62c-d3bc0789d30d")
                    .build()
            )
        )
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

resources: List<ResourceItemDto> — Resources to assign to the project.

client.projects.removeResourceFromProject(projectId, resourceType, resourceId) -> RemoveResourceResponseDto

📝 Description

Removes a resource from a project. The resource itself is not deleted — it becomes unassigned and continues to exist.

🔌 Usage

client.projects().removeResourceFromProject(
    "60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    ProjectResourceType.JOB,
    "48421e16-1f50-4048-b62c-d3bc0789d30d",
    RemoveResourceFromProjectRequest
        .builder()
        .build()
);

⚙️ Parameters

projectId: String — Unique project identifier.

resourceType: ProjectResourceType

resourceId: String — ID of the resource to remove.

Meta

client.meta.healthCheck() -> HealthCheckResponse

📝 Description

Check API availability.

🔌 Usage

client.meta().healthCheck();

client.meta.getVersion() -> GetVersionResponse

📝 Description

Returns current API version.

🔌 Usage

client.meta().getVersion();

client.meta.getPlanLimits() -> GetPlanLimitsResponseDto

📝 Description

Returns plan features and current usage for the authenticated organization.

🔌 Usage

client.meta().getPlanLimits();