Skip to content

reference.md

Latest commit

 

History

History
5791 lines (4000 loc) · 86.5 KB

reference.md

File metadata and controls

5791 lines (4000 loc) · 86.5 KB
Raw

Reference

Jobs

client.jobs.get_user_jobs(...) -> ListUserJobsResponseDto

📝 Description

Returns all jobs created by the authenticated user.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.get_user_jobs(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

search: typing.Optional[str] — Filter results by text (case-insensitive substring match).

ownership: typing.Optional[OwnershipFilter]

project_id: typing.Optional[str] — Filter results to resources belonging to this project.

mode: typing.Optional[GetUserJobsRequestMode] — Filter results by processing mode. Returns only jobs that ran in the specified mode.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.validate_query(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.validate_query(
    query="Series B funding rounds for SaaS startups",
)

⚙️ Parameters

query: str — Plain text query to validate.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.initialize(...) -> InitializeResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.initialize(
    query="Series B funding rounds for SaaS startups",
    context="Focus on funding amount and company name",
)

⚙️ Parameters

query: Query

context: typing.Optional[Context]

connected_dataset_ids: typing.Optional[typing.List[str]] — Optional list of watchlist dataset IDs connected to this job.

fetch_all_watchlist_news: typing.Optional[bool]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.create_job(...) -> SubmitResponseDto

📝 Description

Submit a query to create a new processing job.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment
import datetime

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.create_job(
    query="Series B funding rounds for SaaS startups",
    context="Focus on funding amount and company name",
    limit=10,
    start_date=datetime.datetime.fromisoformat("2026-02-18T00:00:00+00:00"),
    end_date=datetime.datetime.fromisoformat("2026-02-23T00:00:00+00:00"),
    mode="base",
)

⚙️ Parameters

query: Query

context: typing.Optional[Context]

limit: typing.Optional[Limit]

start_date: typing.Optional[StartDate]

end_date: typing.Optional[EndDate]

validators: typing.Optional[typing.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: typing.Optional[typing.List[EnrichmentSchema]]

Custom enrichment fields for data extraction.

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

mode: typing.Optional[SubmitRequestDtoMode]

Job processing mode.

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

connected_dataset_ids: typing.Optional[typing.List[str]]

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.

ed_score_min: typing.Optional[int]

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.

project_id: typing.Optional[str] — Project to assign this job to. The job appears in the project's resource list immediately after submission.

webhook_ids: typing.Optional[typing.List[str]] — IDs of webhooks to notify when the job completes. Maximum 5 per job.

fetch_all_watchlist_news: typing.Optional[bool]

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

ed_association_type: typing.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.

source_groups: typing.Optional[typing.List[str]]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_status(...) -> StatusResponseDto

📝 Description

Retrieve the current processing status of a job.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.get_job_status(
    job_id="5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
)

⚙️ Parameters

job_id: str — Unique job identifier returned from POST /catchAll/submit.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_results(...) -> PullJobResponseDto

📝 Description

Retrieve the final results for a completed job.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.get_job_results(
    job_id="5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
)

⚙️ Parameters

job_id: str — Unique job identifier returned from POST /catchAll/submit.

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.get_job_results_csv(...) -> str

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.get_job_results_csv(
    job_id="job_id",
)

⚙️ Parameters

job_id: str — Unique job identifier returned from POST /catchAll/submit.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.continue_job(...) -> ContinueResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.continue_job(
    job_id="5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    new_limit=100,
)

⚙️ Parameters

job_id: str — Job identifier of the completed job to continue.

new_limit: typing.Optional[int] — New record limit for continued processing. Must be greater than the previous limit. If not provided, defaults to the plan maximum.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.delete_job(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.delete_job(
    job_id="5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
)

⚙️ Parameters

job_id: str — Unique job identifier returned from POST /catchAll/submit.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.list_source_groups(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.jobs.list_source_groups()

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of source groups per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Event Monitors

client.event_monitors.list_monitors(...) -> ListMonitorsResponseDto

📝 Description

Returns all event monitors created by the authenticated user.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.list_monitors(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

search: typing.Optional[str] — Filter results by text (case-insensitive substring match).

ownership: typing.Optional[OwnershipFilter]

project_id: typing.Optional[str] — Filter results to resources belonging to this project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.create_monitor(...) -> CreateMonitorResponseDto

📝 Description

Create a scheduled event monitor based on a reference job.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.create_monitor(
    reference_job_id="5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    schedule="every day at 12 PM",
    timezone="UTC",
    webhook_ids=[
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ],
    limit=10,
    backfill=True,
)

⚙️ Parameters

reference_job_id: str

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: str — Event monitor schedule in plain text format. Minimum frequency depends on your plan.

timezone: typing.Optional[str]

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.

webhook_ids: typing.Optional[typing.List[str]]

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: typing.Optional[int] — Maximum number of records per event monitor run. If not provided, defaults to the plan limit.

backfill: typing.Optional[bool]

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.

project_id: typing.Optional[str] — Project to assign this event monitor to. The event monitor appears in the project's resource list after creation.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.pull_monitor_results(...) -> PullMonitorResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.pull_monitor_results(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.pull_monitor_results_csv(...) -> str

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.pull_monitor_results_csv(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.list_monitor_jobs(...) -> ListMonitorJobsResponse

📝 Description

Return all jobs executed by an event monitor.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.list_monitor_jobs(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

sort: typing.Optional[ListMonitorJobsRequestSort] — Sort by start_date (asc or desc).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.get_monitor_status_history(...) -> MonitorStatusHistoryResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.get_monitor_status_history(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.enable_monitor(...) -> EnableMonitorResponse

📝 Description

Resume scheduled job execution for an event monitor.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.enable_monitor(
    monitor_id="monitor_id",
    backfill=True,
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

backfill: typing.Optional[bool]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.disable_monitor(...) -> DisableMonitorResponse

📝 Description

Stop scheduled job execution for an event monitor.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.disable_monitor(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.delete_monitor(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.delete_monitor(
    monitor_id="monitor_id",
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.event_monitors.update_monitor(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.event_monitors.update_monitor(
    monitor_id="monitor_id",
    webhook_ids=[
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ],
)

⚙️ Parameters

monitor_id: str — Event monitor identifier.

webhook_ids: typing.Optional[typing.List[str]]

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: typing.Optional[int] — Updated maximum number of records per event monitor run.

schedule: typing.Optional[str]

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: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhooks

client.webhooks.list_webhooks(...) -> ListWebhooksResponseDto

📝 Description

Returns a paginated list of webhooks belonging to the organization.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.list_webhooks(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of webhooks per page.

search: typing.Optional[str] — Filter results by text (case-insensitive substring match).

project_id: typing.Optional[str] — Filter results to resources belonging to this project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.create_webhook(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.create_webhook(
    name="Layoffs Alert",
    url="https://hooks.slack.com/services/T000/B000/xxx",
    type="slack",
    delivery_mode="full",
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

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

url: str

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: typing.Optional[WebhookType]

delivery_mode: typing.Optional[DeliveryMode]

method: typing.Optional[HttpMethod]

headers: typing.Optional[typing.Dict[str, str]] — Custom HTTP headers forwarded with each delivery.

params: typing.Optional[typing.Dict[str, str]] — Query parameters appended to the webhook URL.

auth: typing.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.

formatter_config: typing.Optional[FormatterConfigDto] — Custom payload formatter. Required when type is custom.

project_id: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.get_webhook(...) -> GetWebhookResponseDto

📝 Description

Returns the full configuration of a single webhook by ID.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.get_webhook(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.delete_webhook(...)

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.delete_webhook(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.update_webhook(...) -> UpdateWebhookResponseDto

📝 Description

Updates one or more fields of an existing webhook.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.update_webhook(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    name="Layoffs Alert (EU)",
    is_active=False,
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

name: typing.Optional[str] — Updated webhook name.

url: typing.Optional[str] — Updated destination URL. Must use HTTPS. Type-specific URL rules apply.

type: typing.Optional[WebhookType]

delivery_mode: typing.Optional[DeliveryMode]

method: typing.Optional[HttpMethod]

headers: typing.Optional[typing.Dict[str, str]] — Updated HTTP headers. Replaces existing headers entirely.

params: typing.Optional[typing.Dict[str, str]] — Updated query parameters. Replaces existing params entirely.

auth: typing.Optional[UpdateWebhookRequestDtoAuth] — Updated authentication configuration. Replaces existing auth entirely.

formatter_config: typing.Optional[FormatterConfigDto] — Updated custom payload formatter. Set only when type is custom.

is_active: typing.Optional[bool] — Set to false to disable delivery without deleting the webhook.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.test_webhook(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.test_webhook(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    payload={
        "test": True,
        "message": "CatchAll webhook test"
    },
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

payload: typing.Optional[typing.Dict[str, typing.Any]]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.list_webhook_resources(...) -> ListWebhookResourcesResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.list_webhook_resources(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

resource_type: typing.Optional[MappableResourceType]

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of assignments per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.assign_webhook_resource(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.assign_webhook_resource(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    resource_type="monitor",
    resource_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

resource_type: MappableResourceType — Type of resource to assign.

resource_id: str — ID of the resource to assign.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.remove_webhook_resource(...)

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.remove_webhook_resource(
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    resource_type="job",
    resource_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
)

⚙️ Parameters

webhook_id: str — Unique webhook identifier.

resource_type: MappableResourceType

resource_id: str — Unique resource identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.list_webhooks_for_resource(...) -> ListWebhooksResponseDto

📝 Description

Returns all webhooks currently assigned to the given resource.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.list_webhooks_for_resource(
    resource_type="job",
    resource_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
)

⚙️ Parameters

resource_type: MappableResourceType

resource_id: str — Unique resource identifier.

is_active: typing.Optional[bool] — Filter by active status. Omit to return webhooks regardless of status.

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of webhooks per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.trigger_webhook(...)

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.trigger_webhook(
    resource_type="job",
    resource_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
    webhook_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    job_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
)

⚙️ Parameters

resource_type: MappableResourceType

resource_id: str — Unique resource identifier.

webhook_id: str — Identifier of the webhook to trigger. Must be assigned to the resource.

job_id: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.get_webhook_delivery_history(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.webhooks.get_webhook_delivery_history(
    resource_type="job",
    resource_id="3fec5b07-8786-46d7-9486-d43ff67eccd4",
)

⚙️ Parameters

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

resource_id: str — Identifier of the resource to retrieve delivery history for.

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Entities

client.entities.list_entities(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.list_entities(
    search="NewsCatcher",
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of entities per page.

search: typing.Optional[str] — Filter entities by name (case-insensitive substring match).

status: typing.Optional[EntityStatus]

entity_type: typing.Optional[EntityType]

sort_by: typing.Optional[EntitySortBy]

sort_order: typing.Optional[SortOrder]

project_id: typing.Optional[str] — Filter results to resources belonging to this project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.entities.create_entity(...) -> 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

from newscatcher_catchall import CatchAllApi, AdditionalAttributes, CompanyAttributes
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.create_entity(
    name="NewsCatcher",
    entity_type="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).",
    additional_attributes=AdditionalAttributes(
        company_attributes=CompanyAttributes(
            domain="newscatcherapi.com",
            key_persons=[
                "Artem Bugara",
                "Maksym Sugonyaka"
            ],
            alternative_names=[
                "NewsCatcher CatchAll",
                "NewsCatcher API"
            ],
        ),
    ),
)

⚙️ Parameters

request: CreateEntityRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.entities.create_entities_batch(...) -> 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

from newscatcher_catchall import CatchAllApi, CreateEntityRequest, AdditionalAttributes, CompanyAttributes
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.create_entities_batch(
    entities=[
        CreateEntityRequest(
            name="OpenAI",
            entity_type="company",
            description="Artificial intelligence research company",
            additional_attributes=AdditionalAttributes(
                company_attributes=CompanyAttributes(
                    domain="openai.com",
                    key_persons=[
                        "Sam Altman"
                    ],
                    alternative_names=[
                        "Open AI"
                    ],
                ),
            ),
        ),
        CreateEntityRequest(
            name="Stripe",
            entity_type="company",
            description="Online payment processing platform",
            additional_attributes=AdditionalAttributes(
                company_attributes=CompanyAttributes(
                    domain="stripe.com",
                    key_persons=[
                        "Patrick Collison",
                        "John Collison"
                    ],
                ),
            ),
        )
    ],
)

⚙️ Parameters

entities: typing.List[CreateEntityRequest]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.entities.get_entity(...) -> EntityResponse

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.get_entity(
    entity_id="854198fa-f702-49db-a381-0427fa87f173",
)

⚙️ Parameters

entity_id: str — Unique entity identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.entities.delete_entity(...)

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.delete_entity(
    entity_id="854198fa-f702-49db-a381-0427fa87f173",
)

⚙️ Parameters

entity_id: str — Unique entity identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.entities.update_entity(...) -> EntityResponse

📝 Description

Updates one or more fields of an existing entity.

🔌 Usage

from newscatcher_catchall import CatchAllApi, AdditionalAttributes, CompanyAttributes
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.entities.update_entity(
    entity_id="854198fa-f702-49db-a381-0427fa87f173",
    description="Updated description",
    additional_attributes=AdditionalAttributes(
        company_attributes=CompanyAttributes(
            alternative_names=[
                "NewsCatcher CatchAll",
                "NewsCatcher API",
                "NCA"
            ],
        ),
    ),
)

⚙️ Parameters

entity_id: str — Unique entity identifier.

name: typing.Optional[str] — Updated entity name.

description: typing.Optional[str] — Updated description.

external_entity_id: typing.Optional[str] — Updated external identifier for this entity.

additional_attributes: typing.Optional[AdditionalAttributes]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Datasets

client.datasets.list_datasets(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.list_datasets(
    search="Portfolio",
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of datasets per page.

search: typing.Optional[str] — Filter datasets by name (case-insensitive substring match).

latest_status: typing.Optional[DatasetStatus] — Filter by dataset status.

sort_by: typing.Optional[DatasetSortBy]

sort_order: typing.Optional[SortOrder]

ownership: typing.Optional[OwnershipFilter]

project_id: typing.Optional[str] — Filter results to resources belonging to this project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.create_dataset(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.create_dataset(
    name="My Portfolio",
    description="Companies in our investment portfolio",
    entity_ids=[
        "854198fa-f702-49db-a381-0427fa87f173",
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ],
)

⚙️ Parameters

name: str — Name for the dataset.

description: typing.Optional[str] — Optional description.

entity_ids: typing.Optional[typing.List[str]] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.create_dataset_from_csv(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.create_dataset_from_csv(
    file="example_file",
    name="name",
)

⚙️ Parameters

file: core.File — The CSV file to upload.

name: str — Name for the new dataset.

description: typing.Optional[str] — Optional description for the dataset.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.get_dataset(...) -> DatasetResponse

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.get_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.delete_dataset(...)

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.delete_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.update_dataset(...) -> DatasetResponse

📝 Description

Updates the name or description of a dataset.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.update_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
    name="My Portfolio (updated)",
    description="Updated Q1 2026 watchlist",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

name: typing.Optional[str] — Updated dataset name.

description: typing.Optional[str] — Updated description.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.add_entities_to_dataset(...) -> ManageEntitiesResponse

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.add_entities_to_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
    entity_ids=[
        "854198fa-f702-49db-a381-0427fa87f173"
    ],
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

request: DatasetEntityIdsRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.remove_entities_from_dataset(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.remove_entities_from_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
    entity_ids=[
        "854198fa-f702-49db-a381-0427fa87f173"
    ],
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

request: DatasetEntityIdsRequest

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.list_entities_in_dataset(...) -> DatasetEntityListResponse

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.list_entities_in_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
    page=1,
    page_size=100,
    search="OpenAI",
    status="ready",
    entity_type="company",
    sort_by="created_at",
    sort_order="desc",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

page: typing.Optional[int] — The page number to retrieve.

page_size: typing.Optional[int] — The number of entities per page.

search: typing.Optional[str] — Filters entities by name using a case-insensitive substring match.

status: typing.Optional[EntityStatus]

entity_type: typing.Optional[EntityType]

sort_by: typing.Optional[EntitySortBy]

sort_order: typing.Optional[SortOrder]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.get_dataset_status_history(...) -> DatasetStatusHistoryResponse

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.get_dataset_status_history(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.datasets.upload_csv_to_dataset(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.datasets.upload_csv_to_dataset(
    dataset_id="ccabb755-afc2-4047-b84c-78d1f23d49b2",
    file="example_file",
)

⚙️ Parameters

dataset_id: str — Unique dataset identifier.

file: core.File — The CSV file to upload.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Projects

client.projects.list_projects(...) -> ProjectListResponseDto

📝 Description

Returns all projects visible to the authenticated user.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.list_projects(
    search="M&A",
)

⚙️ Parameters

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

search: typing.Optional[str] — Filter by project name (case-insensitive substring match).

ownership: typing.Optional[OwnershipFilter]

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.create_project(...) -> CreateProjectResponseDto

📝 Description

Creates a new project.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.create_project(
    name="AI M&A Tracking",
    description="Tracks AI-related M&A activity for our investment team.",
)

⚙️ Parameters

name: str — Name for the project.

description: typing.Optional[str] — Optional description.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.get_project(...) -> ProjectResponseDto

📝 Description

Returns a single project by ID.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.get_project(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

project_id: str — Unique project identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.delete_project(...)

📝 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.delete_project(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

project_id: str — Unique project identifier.

delete_resources: typing.Optional[bool]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.update_project(...) -> UpdateProjectResponseDto

📝 Description

Updates the name or description of an existing project.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.update_project(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    name="AI M&A Tracking (Q2 2026)",
)

⚙️ Parameters

project_id: str — Unique project identifier.

name: typing.Optional[str] — New name for the project.

description: typing.Optional[str] — New description for the project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.get_project_overview(...) -> 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

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.get_project_overview(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

project_id: str — Unique project identifier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.list_project_resources(...) -> ProjectResourceListResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.list_project_resources(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
)

⚙️ Parameters

project_id: str — Unique project identifier.

resource_type: typing.Optional[ProjectResourceType]

page: typing.Optional[int] — Page number to retrieve.

page_size: typing.Optional[int] — Number of records per page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.add_resource_to_project(...) -> AddResourceResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi, ResourceItemDto
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.add_resource_to_project(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    resources=[
        ResourceItemDto(
            resource_type="job",
            resource_id="48421e16-1f50-4048-b62c-d3bc0789d30d",
        )
    ],
)

⚙️ Parameters

project_id: str — Unique project identifier.

resources: typing.List[ResourceItemDto] — Resources to assign to the project.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.projects.remove_resource_from_project(...) -> RemoveResourceResponseDto

📝 Description

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

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.projects.remove_resource_from_project(
    project_id="60a85db4-78ec-4b78-876a-bc7d9cdadd04",
    resource_type="job",
    resource_id="48421e16-1f50-4048-b62c-d3bc0789d30d",
)

⚙️ Parameters

project_id: str — Unique project identifier.

resource_type: ProjectResourceType

resource_id: str — ID of the resource to remove.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Meta

client.meta.health_check() -> HealthCheckResponse

📝 Description

Check API availability.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.meta.health_check()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.meta.get_version() -> GetVersionResponse

📝 Description

Returns current API version.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.meta.get_version()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.meta.get_plan_limits() -> GetPlanLimitsResponseDto

📝 Description

Returns plan features and current usage for the authenticated organization.

🔌 Usage

from newscatcher_catchall import CatchAllApi
from newscatcher_catchall.environment import CatchAllApiEnvironment

client = CatchAllApi(
    api_key="<value>",
    environment=CatchAllApiEnvironment.DEFAULT,
)

client.meta.get_plan_limits()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.