diff --git a/llms.txt b/llms.txt index fcf4396..2cb27fb 100644 --- a/llms.txt +++ b/llms.txt @@ -80,7 +80,13 @@ If the event monitor's reference job used connected entity datasets, connected e - [Enable Monitor](https://www.newscatcherapi.com/docs/web-search-api/api-reference/event-monitors/enable-monitor): Resume scheduled job execution for an event monitor. - [Disable Monitor](https://www.newscatcherapi.com/docs/web-search-api/api-reference/event-monitors/disable-monitor): Stop scheduled job execution for an event monitor. -- [Update Monitor](https://www.newscatcherapi.com/docs/web-search-api/api-reference/event-monitors/update-monitor): Update the webhook configuration for an existing event monitor. +- [Update Monitor](https://www.newscatcherapi.com/docs/web-search-api/api-reference/event-monitors/update-monitor): 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. + - [Delete Monitor](https://www.newscatcherapi.com/docs/web-search-api/api-reference/event-monitors/delete-monitor): Soft-deletes an event monitor. The event monitor is flagged as deleted, stops executing scheduled jobs immediately, and no longer appears in list results. diff --git a/web-search-api/api-reference/catch-all-api.yml b/web-search-api/api-reference/catch-all-api.yml index 958e07c..272d3fb 100644 --- a/web-search-api/api-reference/catch-all-api.yml +++ b/web-search-api/api-reference/catch-all-api.yml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: NewsCatcher CatchAll API - version: 1.8.1 + version: 1.8.2 description: | CatchAll is a web search API that generates unique datasets that don't exist anywhere else on the web. Built on NewsCatcher's proprietary real-world event index, it delivers state-of-the-art recall—finding all relevant events, not just top results. @@ -675,7 +675,13 @@ paths: tags: - Event Monitors summary: Update event monitor - description: Update the webhook configuration for an existing event monitor. + 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. operationId: updateMonitor externalDocs: description: Learn about event monitor configuration @@ -694,9 +700,17 @@ paths: application/json: schema: $ref: "#/components/schemas/UpdateMonitorRequestDto" - example: - webhook_ids: - - "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + examples: + update_webhooks: + summary: Update webhook assignments + value: + webhook_ids: + - "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + update_schedule: + summary: Change the schedule + value: + schedule: "every Monday at 9 AM" + timezone: "America/New_York" responses: "200": $ref: "#/components/responses/UpdateMonitorResponse" @@ -707,7 +721,13 @@ paths: "404": $ref: "#/components/responses/NotFoundError" "422": - $ref: "#/components/responses/ValidationError" + description: | + Validation error. Also returned when `schedule` can't be parsed into a + cron expression, or when runs would be spaced too closely. + content: + application/json: + schema: + $ref: "#/components/schemas/ValidationErrorResponse" delete: tags: @@ -5020,6 +5040,24 @@ components: type: integer minimum: 10 description: Updated maximum number of records per event monitor run. + schedule: + type: [string, "null"] + description: | + 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. + example: "every day at 9 AM" + timezone: + type: [string, "null"] + default: UTC + description: | + 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. + example: "America/New_York" UpdateMonitorResponseDto: type: object diff --git a/web-search-api/api-reference/fastapi-openapi.yml b/web-search-api/api-reference/fastapi-openapi.yml index 21fdf11..8cff135 100644 --- a/web-search-api/api-reference/fastapi-openapi.yml +++ b/web-search-api/api-reference/fastapi-openapi.yml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: NewsCatcher CatchAll API - version: 1.8.1 + version: 1.10.0 contact: name: NewsCatcher url: https://newscatcherapi.com @@ -31,12 +31,12 @@ info: 4. Retrieve results via /catchAll/pull/{job_id} - ### Event monitor workflow + ### Monitor workflow 1. Create successful job via /catchAll/submit - 2. Create event monitor via /catchAll/monitors/create with schedule + 2. Create monitor via /catchAll/monitors/create with schedule 3. Retrieve aggregated results via /catchAll/monitors/pull/{monitor_id} @@ -536,10 +536,10 @@ paths: /catchAll/monitors/create: post: tags: - - Event Monitors - summary: Create an event monitor - description: 'Creates a scheduled event monitor from a reference completed job. The - event monitor re-runs the reference job''s query/validators/enrichments on a cron + - Monitors + summary: Create a monitor + description: 'Creates a scheduled monitor from a reference completed job. The + monitor re-runs the reference job''s query/validators/enrichments on a cron schedule. @@ -572,15 +572,15 @@ paths: '422': description: Schedule could not be parsed into a cron expression '429': - description: Event monitor active slots limit reached + description: Monitor active slots limit reached '401': description: Missing or invalid authentication credentials. /catchAll/monitors/{monitor_id}/status: get: tags: - - Event Monitors - summary: Get event monitor status history - description: Returns all status entries for an event monitor, ordered newest-first. + - Monitors + summary: Get monitor status history + description: Returns all status entries for a monitor, ordered newest-first. Each entry has a status type, timestamp, and additional_information dict. operationId: getMonitorStatusHistory parameters: @@ -599,9 +599,9 @@ paths: schema: $ref: '#/components/schemas/MonitorStatusHistoryResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found or no status entries yet + description: Monitor not found or no status entries yet '422': description: Validation Error content: @@ -613,9 +613,9 @@ paths: /catchAll/monitors/{monitor_id}/jobs: get: tags: - - Event Monitors - summary: List jobs spawned by an event monitor - description: Returns all jobs created by past event monitor runs, sorted by start_date. + - Monitors + summary: List jobs spawned by a monitor + description: Returns all jobs created by past monitor runs, sorted by start_date. Each entry includes job_id, start_date, and end_date. operationId: listMonitorJobs parameters: @@ -644,9 +644,9 @@ paths: schema: $ref: '#/components/schemas/ListMonitorJobsResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: No jobs found for this event monitor + description: No jobs found for this monitor '422': description: Validation Error content: @@ -658,8 +658,8 @@ paths: /catchAll/monitors/pull/{monitor_id}: get: tags: - - Event Monitors - summary: Pull latest results for an event monitor + - Monitors + summary: Pull latest results for a monitor description: Returns the most recent run's aggregated records. Structure mirrors job pull with the addition of cron_expression and reference_job. operationId: pullMonitorResults @@ -678,9 +678,9 @@ paths: schema: $ref: '#/components/schemas/PullMonitorResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found or no results yet + description: Monitor not found or no results yet '422': description: Validation Error content: @@ -692,8 +692,8 @@ paths: /catchAll/monitors/pull/{monitor_id}/csv: get: tags: - - Event Monitors - summary: Pull latest event monitor results as CSV + - Monitors + summary: Pull latest monitor results as CSV 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 entity datasets were used, connected entities are split into event_associated_entities @@ -714,9 +714,9 @@ paths: schema: {} text/csv: {} '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found or no results yet + description: Monitor not found or no results yet '422': description: Validation Error content: @@ -728,9 +728,9 @@ paths: /catchAll/monitors/{monitor_id}/disable: post: tags: - - Event Monitors - summary: Disable an event monitor - description: Pauses future runs without deleting the event monitor or releasing the + - Monitors + summary: Disable a monitor + description: Pauses future runs without deleting the monitor or releasing the entitlement slot. operationId: disableMonitor parameters: @@ -749,9 +749,9 @@ paths: schema: $ref: '#/components/schemas/DisableMonitorResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found + description: Monitor not found '422': description: Validation Error content: @@ -763,9 +763,9 @@ paths: /catchAll/monitors/{monitor_id}/enable: post: tags: - - Event Monitors - summary: Enable (re-activate) an event monitor - description: 'Re-activates a disabled event monitor. The Monitor_Active_Slots entitlement + - Monitors + summary: Enable (re-activate) a monitor + description: 'Re-activates a disabled monitor. The Monitor_Active_Slots entitlement is re-reserved. @@ -796,11 +796,11 @@ paths: schema: $ref: '#/components/schemas/EnableMonitorResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found + description: Monitor not found '429': - description: Event monitor active slots limit reached + description: Monitor active slots limit reached '422': description: Validation Error content: @@ -812,10 +812,12 @@ paths: /catchAll/monitors/{monitor_id}: patch: tags: - - Event Monitors - summary: Update webhook assignments or limit - description: 'Updates the webhook assignments and/or result limit for an event monitor. - Pass an empty `webhook_ids: []` to clear all webhook assignments.' + - Monitors + summary: Update webhook assignments, limit, or schedule + description: 'Updates the webhook assignments, result limit, and/or schedule + for a monitor. Pass an empty `webhook_ids: []` to clear all webhook assignments. + Passing `schedule` replaces the monitor''s cron schedule; the running scheduler + picks up the new schedule on its next reload and the old one stops firing.' operationId: updateMonitor parameters: - name: monitor_id @@ -841,25 +843,22 @@ paths: '400': description: Validation error or webhook limit exceeded (max 5 per resource) '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor or webhook not found + description: Monitor or webhook not found '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + description: Schedule could not be parsed into a cron expression, or runs + would be spaced too closely '401': description: Missing or invalid authentication credentials. externalDocs: - description: Learn about event monitor configuration - url: https://www.newscatcherapi.com/docs/web-search-api/how-to/configure-event-monitors + description: Learn about monitor configuration + url: https://www.newscatcherapi.com/docs/web-search-api/how-to/configure-monitors delete: tags: - - Event Monitors - summary: Delete an event monitor - description: Soft-deletes an event monitor and releases the Monitor_Active_Slots entitlement. + - Monitors + summary: Delete a monitor + description: Soft-deletes a monitor and releases the Monitor_Active_Slots entitlement. operationId: deleteMonitor parameters: - name: monitor_id @@ -877,9 +876,9 @@ paths: schema: $ref: '#/components/schemas/DeleteMonitorResponseDto' '403': - description: Event monitor does not belong to this user + description: Monitor does not belong to this user '404': - description: Event monitor not found + description: Monitor not found '422': description: Validation Error content: @@ -891,9 +890,9 @@ paths: /catchAll/monitors: get: tags: - - Event Monitors - summary: List event monitors for the authenticated API key - description: Returns event monitors owned by or shared with the caller. API key values + - Monitors + summary: List monitors for the authenticated API key + description: Returns monitors owned by or shared with the caller. API key values are masked. operationId: listMonitors parameters: @@ -1653,7 +1652,7 @@ paths: - Projects summary: Create project description: Creates a new project for the organization. Projects are named - containers used to group related jobs, event monitors, datasets, event monitor groups, + containers used to group related jobs, monitors, datasets, monitor groups, and webhooks. operationId: createProject requestBody: @@ -1805,8 +1804,8 @@ paths: tags: - Projects summary: Delete project - description: 'Deletes a project. If delete_resources=true, all jobs, event monitors, - datasets, and event monitor groups in the project are also deleted. Webhooks are + description: 'Deletes a project. If delete_resources=true, all jobs, monitors, + datasets, and monitor groups in the project are also deleted. Webhooks are handled differently: they are never deleted by this operation — any attached webhook is simply detached from the project and continues to exist and remain fully usable/shareable on its own, since a webhook can be attached to other @@ -1854,7 +1853,7 @@ paths: - Projects summary: Get project overview description: 'Returns a high-level summary of a project: total resource counts - by type (jobs, event monitors, datasets, event monitor groups, webhooks).' + by type (jobs, monitors, datasets, monitor groups, webhooks).' operationId: getProjectOverview parameters: - name: project_id @@ -1888,8 +1887,8 @@ paths: tags: - Projects summary: Add resources to project - description: Attaches one or more existing resources (job, event monitor, dataset, - event monitor group, or webhook) to a project. Returns 201 when at least one resource + description: Attaches one or more existing resources (job, monitor, dataset, + monitor_group, or webhook) to a project. Returns 201 when at least one resource is newly attached, 200 if all were already associated. operationId: addResourceToProject parameters: @@ -2268,7 +2267,7 @@ paths: tags: - Webhooks summary: Assign resource to webhook - description: Attaches a job, event monitor, or event monitor group to a webhook so it receives + description: Attaches a job, monitor, or monitor_group to a webhook so it receives delivery on completion. Returns 201 on new assignment, 200 if already assigned. A webhook can be assigned to multiple resources; each resource can have multiple webhooks (up to plan limit). @@ -2312,7 +2311,7 @@ paths: tags: - Webhooks summary: List webhook resources - description: Returns a paginated list of resources (jobs, event monitors, event monitor groups) + description: Returns a paginated list of resources (jobs, monitors, monitor_groups) currently assigned to this webhook. Filter by resource_type. operationId: listWebhookResources parameters: @@ -2372,7 +2371,7 @@ paths: tags: - Webhooks summary: Remove resource from webhook - description: Detaches a specific resource from this webhook. Future job/event monitor + description: Detaches a specific resource from this webhook. Future job/monitor runs will no longer trigger delivery to this webhook. Returns 204 No Content. operationId: removeWebhookResource parameters: @@ -2416,7 +2415,7 @@ paths: - Webhooks summary: List webhooks for a resource description: Returns all webhooks currently assigned to the given resource (job, - event monitor, or event monitor group). Use is_active filter to see only active or inactive + monitor, or monitor_group). Use is_active filter to see only active or inactive webhooks. operationId: listWebhooksForResource parameters: @@ -2505,9 +2504,9 @@ paths: anyOf: - $ref: '#/components/schemas/MappableResourceType' - type: 'null' - description: 'Resource type: job, event monitor, event monitor group' + description: 'Resource type: job, monitor, monitor_group' title: Resource Type - description: 'Resource type: job, event monitor, event monitor group' + description: 'Resource type: job, monitor, monitor_group' - name: resource_id in: query required: false @@ -2659,46 +2658,46 @@ tags: externalDocs: description: Learn about job lifecycle and status tracking url: https://www.newscatcherapi.com/docs/web-search-api/get-started/quickstart -- name: Event Monitors - description: Operations to create, operate and retrieve event monitor results. +- name: Monitors + description: Operations to create, operate and retrieve monitor results. externalDocs: description: Automate recurring queries with scheduled jobs and webhook notifications. - url: https://www.newscatcherapi.com/docs/web-search-api/concepts/event-monitors + url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/monitors - name: Entities description: 'Operations to create, update, and delete company entities. - Entities are the building blocks of Company Monitors. Each entity represents + Entities are the building blocks of Company Watchlist. Each entity represents a company (or person) you want to track. Add identifying information such as domain, alternative names, and key persons to improve matching quality.' externalDocs: - description: Learn about Company Monitors and entities - url: https://www.newscatcherapi.com/docs/web-search-api/concepts/company-monitors + description: Learn about Company Watchlist and entities + url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search - name: Datasets description: 'Operations to create and manage datasets of entities. A dataset is a named collection of entities — think of it as a watchlist or portfolio. - Connect a dataset to a job via `connected_dataset_ids` to activate Company Monitors. - Datasets can be reused across multiple jobs and event monitors.' + Connect a dataset to a job via `connected_dataset_ids` to activate Company Watchlist. + Datasets can be reused across multiple jobs and monitors.' externalDocs: - description: Learn about datasets and Company Monitors - url: https://www.newscatcherapi.com/docs/web-search-api/concepts/company-monitors + description: Learn about datasets and Company Watchlist + url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search - name: Projects description: 'Operations to create, organize, and manage projects. - A project is a named container for jobs, event monitors, and datasets. Group related + A project is a named container for jobs, monitors, and datasets. Group related resources by use case, team, or client, and share them with teammates. Resources can be assigned at creation time or post-hoc.' externalDocs: description: Learn about projects and resource organization - url: https://www.newscatcherapi.com/docs/web-search-api/concepts/projects + url: https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/projects - name: Webhooks description: 'Operations to create, manage, and test webhooks. - Webhooks deliver real-time notifications to your endpoint when event monitor jobs complete. + Webhooks deliver real-time notifications to your endpoint when monitor jobs complete. Configure URL, authentication, headers, and delivery mode.' externalDocs: description: Learn about webhooks and notifications @@ -2707,15 +2706,15 @@ tags: description: Operations to check API health and version. components: schemas: - HTTPValidationError: + CheckQueryQualityRequestDto: properties: - detail: - items: - $ref: '#/components/schemas/ValidationError' - type: array - title: Detail + query: + type: string + title: Query type: object - title: HTTPValidationError + required: + - query + title: CheckQueryQualityRequestDto CheckQueryQualityResponseDto: properties: status: @@ -2757,280 +2756,181 @@ components: - confidence title: CheckQueryQualityResponseDto description: Complete query validation result - CheckQueryQualityRequestDto: - properties: - query: - type: string - title: Query - type: object - required: - - query - title: CheckQueryQualityRequestDto - DatasetStatus: - type: string - enum: - - pending - - enriching - - ready - - failed - title: DatasetStatus - description: 'Processing status of a dataset: pending → enriching → ready. Failed - indicates one or more entity enrichments failed.' - SubmitResponseDto: - properties: - job_id: - type: string - format: uuid - title: Job Id - description: UUID of the created job. Use this in /status and /pull. - example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - type: object - required: - - job_id - title: SubmitResponseDto - GetWebhookResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - webhook: - anyOf: - - $ref: '#/components/schemas/WebhookResponseDto' - - type: 'null' - description: Webhook details. - type: object - required: - - success - - message - title: GetWebhookResponseDto - AddResourceRequestDto: + HTTPValidationError: properties: - resources: + detail: items: - $ref: '#/components/schemas/ResourceItemRequestDto' + $ref: '#/components/schemas/ValidationError' type: array - title: Resources - description: Resources to assign to the project. - type: object - required: - - resources - title: AddResourceRequestDto - UpdateMonitorResponseDto: - properties: - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: Event monitor identifier. - status: - type: string - title: Status - description: Confirmation message. - default: Monitor updated Successfully + title: Detail type: object - title: UpdateMonitorResponseDto - CreateEntitiesBatchResponseDto: + title: HTTPValidationError + CreateEntitiesBatchRequestDto: properties: entities: items: - $ref: '#/components/schemas/CreateEntityResponseDto' + $ref: '#/components/schemas/CreateEntityRequestDto' type: array title: Entities - description: Array of created entity stubs in the same order as the input. - count: - type: integer - title: Count - description: Total number of entities created. + description: Array of entities to create. type: object required: - entities - - count - title: CreateEntitiesBatchResponse - UpdateMonitorRequestDto: - properties: - webhook_ids: - anyOf: - - items: - type: string - format: uuid - type: array - - type: 'null' - title: Webhook Ids - description: Optional list of centralized webhook IDs to assign to this - event monitor. Empty list clears assignments. - limit: - anyOf: - - type: integer - - type: 'null' - title: Limit - description: Optional max results per event monitor run (min 10, validated against - plan) - type: object - title: UpdateMonitorRequestDto - MappableResourceType: - type: string - enum: - - job - - monitor - - monitor_group - title: MappableResourceType - description: 'Resource types that can be assigned to a webhook: job, event monitor, - or event monitor group.' - GetProjectResponseDto: + title: CreateEntitiesBatchRequest + MonitorStatusHistoryResponseDto: properties: success: type: boolean title: Success - description: True if the operation succeeded; false otherwise. + description: True if the request succeeded; false otherwise. message: - type: string - title: Message - description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project identifier. - name: anyOf: - type: string - type: 'null' - title: Name - description: Project name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Project description. - resources_count: - type: integer - title: Resources Count - description: Number of resources assigned to this project. - default: 0 - created_at: + title: Message + description: Optional message. Null on success. + monitor_id: anyOf: - type: string + format: uuid - type: 'null' - title: Created At - description: Project creation timestamp. - updated_at: + title: Monitor Id + description: Monitor identifier. Null on failure. + total_statuses: anyOf: - - type: string + - type: integer - type: 'null' - title: Updated At - description: Timestamp of the last update. - sharing_info: + title: Total Statuses + description: Total number of status entries in the history. + statuses: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - items: + $ref: '#/components/schemas/MonitorStatusEntryDto' + type: array - type: 'null' - description: Present when this project was shared with the authenticated - user. + title: Statuses + description: Full status history, ordered newest to oldest. type: object required: - success - - message - title: GetProjectResponseDto - DeleteMonitorResponseDto: + title: MonitorStatusHistoryResponseDto + WebhookHistoryByResourceDto: properties: - success: - type: boolean - title: Success - description: True if the delete operation succeeded; false otherwise. - message: + mode: type: string - title: Message - description: Human-readable result message. - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: ID of the deleted event monitor. Null on failure. - type: object - required: - - success - - message - title: DeleteMonitorResponseDto - RemoveResourceResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: + const: resource + title: Mode + default: resource + resource_type: + $ref: '#/components/schemas/MappableResourceType' + resource_id: type: string - title: Message - description: Human-readable result message. + format: uuid + title: Resource Id + total: + type: integer + title: Total + page: + type: integer + title: Page + page_size: + type: integer + title: Page Size + items: + items: + $ref: '#/components/schemas/WebhookStatusItemDto' + type: array + title: Items type: object required: - - success - - message - title: RemoveResourceResponseDto - Body_uploadCSVToDataset: - properties: - file: - type: string - format: binary - title: File - type: object + - resource_type + - resource_id + - total + - page + - page_size + - items + title: WebhookHistoryByResourceDto + ListSourceGroupsApiResponseDto: + properties: + source_groups: + items: + $ref: '#/components/schemas/SourceGroupApiResponseDto' + type: array + title: Source Groups + total: + type: integer + title: Total + page: + type: integer + title: Page + page_size: + type: integer + title: Page Size + type: object required: - - file - title: Body_uploadCSVToDataset - ContinueRequestDto: + - source_groups + - total + - page + - page_size + title: ListSourceGroupsApiResponseDto + ProjectListResponseDto: properties: - job_id: - type: string - format: uuid - title: Job Id - description: Existing job to extend with a higher result limit. - new_limit: - anyOf: - - type: integer - - type: 'null' - title: New Limit - description: New limit, must be greater than the current limit. If null, - raises to the plan maximum. - example: 250 + total: + type: integer + title: Total + description: Total number of projects matching the filter criteria. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of projects per page. + total_pages: + type: integer + title: Total Pages + description: Total number of pages available. + projects: + items: + $ref: '#/components/schemas/ProjectResponseDto' + type: array + title: Projects + description: Projects on this page. type: object required: - - job_id - title: ContinueRequestDto - example: - job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - new_limit: 250 - UpdateProjectRequestDto: + - total + - page + - page_size + - total_pages + - projects + title: ProjectListResponseDto + Body_createDatasetFromCsv: properties: + file: + type: string + format: binary + title: File name: - anyOf: - - type: string - - type: 'null' + type: string title: Name - description: New name for the project. description: - anyOf: - - type: string - - type: 'null' + type: string title: Description - description: New description for the project. + project_id: + type: string + title: Project Id type: object - title: UpdateProjectRequestDto - ListWebhooksForResourceResponseDto: + required: + - file + - name + title: Body_createDatasetFromCsv + ResourceListResponseDto: properties: total: type: integer title: Total - description: Total number of webhooks assigned to this resource. + description: Total number of resources assigned to the project. page: type: integer title: Page @@ -3038,212 +2938,105 @@ components: page_size: type: integer title: Page Size - description: Number of webhooks per page. + description: Number of resources per page. total_pages: type: integer title: Total Pages description: Total number of pages available. - webhooks: + resources: items: - $ref: '#/components/schemas/WebhookResponseDto' + $ref: '#/components/schemas/ResourceItemResponseDto' type: array - title: Webhooks - description: Array of webhook objects. + title: Resources + description: Resources on this page. type: object required: - total - page - page_size - total_pages - - webhooks - title: ListWebhooksForResourceResponseDto - SubmitRequestDto: + - resources + title: ProjectResourceListResponseDto + GetWebhookResponseDto: properties: - query: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: type: string - minLength: 1 - title: Query - description: Natural-language question. Keywords and search queries are - extracted automatically. - schema: + title: Message + description: Human-readable result message. + webhook: anyOf: - - type: string + - $ref: '#/components/schemas/WebhookResponseDto' - type: 'null' - title: Schema - description: 'Advanced: custom JSON schema string that overrides the default - extraction schema. Use POST /initialize to discover a suitable schema.' + description: Webhook details. + type: object + required: + - success + - message + title: GetWebhookResponseDto + SuggestInitializeResponseDto: + properties: + query: + type: string + title: Query + description: Echo of the query from the request. context: anyOf: - type: string - type: 'null' title: Context - description: Additional context to sharpen the search scope (geography, - industry, time frame, etc.). - limit: - anyOf: - - type: integer - minimum: 10.0 - - type: 'null' - title: Limit - description: Maximum number of validated records to collect. Minimum 10. - Defaults to the plan limit. Use POST /continue to raise the limit later. + description: Echo of the context from the request. Null if not provided. start_date: anyOf: - type: string format: date-time - type: 'null' title: Start Date - description: Earliest article date (ISO-8601 or free-text like '2024-01-01'). - If start_date is provided and end_date is omitted, end_date defaults to - now. + description: Suggested start date for web search in ISO 8601 format. end_date: anyOf: - type: string format: date-time - type: 'null' title: End Date - description: Latest article date. Cannot be provided without start_date. + description: Suggested end date for web search in ISO 8601 format. validators: - anyOf: - - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array - - type: 'null' + items: + $ref: '#/components/schemas/ValidatorSchema' + type: array title: Validators - description: Boolean classifiers. Only articles where every validator returns - true are counted in valid_records. Provide at least one item or omit entirely. + description: Suggested validators for filtering relevant web pages. enrichments: - anyOf: - - items: - $ref: '#/components/schemas/EnrichmentSchema' - type: array - - type: 'null' + items: + $ref: '#/components/schemas/EnrichmentSchema' + type: array title: Enrichments - description: Custom extraction fields added to each result record under - enrichments.. Provide at least one item or omit entirely. - mode: - anyOf: - - $ref: '#/components/schemas/ProcessingMode' - - type: 'null' - description: Processing mode. 'base' runs the full pipeline with clustering - and enrichment. 'lite' is faster with no clustering. - default: base - connected_dataset_ids: - anyOf: - - items: - type: string - format: uuid - type: array - - type: 'null' - title: Connected Dataset Ids - description: IDs of datasets whose entities narrow the retrieval scope. - When provided, ed_score_min defaults to 2 if not specified. - ed_score_min: - anyOf: - - type: integer - maximum: 10.0 - minimum: 1.0 - - type: 'null' - title: Ed Score Min - description: Minimum entity-domain relevance score (1–10). Only relevant - when connected_dataset_ids is set. Defaults to 2. - ed_association_type: - anyOf: - - $ref: '#/components/schemas/EntityAssociationType' - - type: 'null' - description: 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. - webhook_ids: - anyOf: - - items: - type: string - format: uuid - type: array - - type: 'null' - title: Webhook Ids - description: Webhook IDs to notify when the job completes. Max 5 per job. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project ID to associate this job with. - fetch_all_watchlist_news: - type: boolean - title: Fetch All Watchlist News - description: When true, retrieves all news for connected Company Monitors - entities without topic filtering. Requires connected_dataset_ids to be - set. - default: false - source_groups: + description: Suggested enrichment fields for data extraction. + date_modification_message: anyOf: - items: type: string type: array - type: 'null' - title: Source Groups - description: Slugs of source groups to scope fetching to their domain allowlists. - Fetch available source groups via GET /catchAll/source-groups. Max 20 - per job. - type: object - required: - - query - title: SubmitRequestDto - example: - context: Focus on US-based companies with 500+ employees. - enrichments: - - description: The company conducting the layoffs. - name: company_name - type: company - - description: Number of employees affected, if mentioned. - name: employees_affected - type: number - limit: 100 - mode: base - query: Tech layoffs in 2024 - start_date: '2024-01-01T00:00:00Z' - validators: - - description: The article specifically covers workforce reductions or layoffs. - name: is_about_layoffs - type: boolean - EntityListResponseDto: - properties: - entities: - items: - $ref: '#/components/schemas/EntityResponseDto' - type: array - title: Entities - description: Array of entity objects for this page. - total: - type: integer - title: Total - description: Total number of entities matching the filter criteria. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of entities per page. + title: Date Modification Message + description: Messages explaining date adjustments due to plan limits. type: object required: - - entities - - total - - page - - page_size - title: EntityListResponse - EntitySortBy: + - query + title: InitializeResponseDto + Ownership: type: string enum: - - created_at - - name - - status - title: EntitySortBy - description: Fields available for sorting entity list results. + - all + - own + - shared + title: Ownership + description: Controls which resources are returned based on ownership. 'all' + returns owned and shared resources, 'own' returns only user-created resources, + 'shared' returns only resources shared by others. CreateWebhookRequestDto: properties: name: @@ -3322,364 +3115,192 @@ components: name: Layoffs Alert type: slack url: https://hooks.slack.com/services/T000/B000/xxxx - EntityStatus: - type: string - enum: - - pending - - enriching - - ready - - failed - title: EntityStatus - description: 'Processing status of an entity: pending → enriching → ready. Failed - entities may still be used but matching quality may be reduced.' - DatasetEntityIdsRequestDto: - properties: - entity_ids: - items: - type: string - format: uuid - type: array - title: Entity Ids - description: List of entity IDs to add or remove. - type: object - required: - - entity_ids - title: DatasetEntityIdsRequest - CreateEntityResponseDto: + EntityResponseDto: properties: id: type: string format: uuid title: Id - description: Unique identifier of the created entity. - status: + description: Unique identifier of the entity. + entity_type: type: string - title: Status - description: Initial status of the entity. Always pending immediately after - creation. - default: pending - type: object - required: - - id - title: CreateEntityResponse - CreateProjectRequestDto: - properties: + title: Entity Type + description: The type of entity. + organization_id: + type: string + title: Organization Id + description: Organization that owns this entity. name: type: string title: Name - description: Name for the project. + description: Entity name. description: anyOf: - type: string - type: 'null' title: Description - description: Optional description. - type: object - required: - - name - title: CreateProjectRequestDto - ProjectResourceTypeEnum: - type: string - enum: - - job - - monitor - - dataset - - monitor_group - - webhook - title: ProjectResourceTypeEnum - description: Resource type for project association. - AssignWebhookResourceResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: + description: Free-text description. + external_entity_id: anyOf: - type: string - type: 'null' - title: Message - description: Human-readable result message. - already_existed: - type: boolean - title: Already Existed - description: True if the mapping already existed. - default: false - mapping: + title: External Entity Id + description: External identifier for this entity. Null when not set. + additional_attributes: anyOf: - - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' + - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - description: Created or existing resource mapping. - type: object - required: - - success - title: AssignWebhookResourceResponseDto - EnableMonitorRequestDto: - properties: - backfill: + description: Type-specific attributes. + status: + $ref: '#/components/schemas/EntityStatus' + description: Processing status of the entity. + created_by_user_id: anyOf: - - type: boolean + - type: string - type: 'null' - title: Backfill - description: If True, enforce lookback check on last job; if False, skip - date check. - default: true + title: Created By User Id + description: ID of the user who created this entity. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: Timestamp of when the entity was created. + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: Timestamp of when the entity was last updated. type: object - title: EnableMonitorRequestDto - description: Optional body for POST /{monitor_id}/enable. - WebhookHistoryByResourceDto: + required: + - id + - entity_type + - organization_id + - name + - status + title: EntityResponse + DatasetListResponseDto: properties: - mode: - type: string - const: resource - title: Mode - default: resource - resource_type: - $ref: '#/components/schemas/MappableResourceType' - resource_id: - type: string - format: uuid - title: Resource Id + datasets: + items: + $ref: '#/components/schemas/DatasetResponseDto' + type: array + title: Datasets + description: Array of dataset objects for this page. total: type: integer title: Total + description: Total number of datasets matching the filter criteria. page: type: integer title: Page + description: Current page number. page_size: type: integer title: Page Size - items: - items: - $ref: '#/components/schemas/WebhookStatusItemDto' - type: array - title: Items + description: Number of datasets per page. type: object required: - - resource_type - - resource_id + - datasets - total - page - page_size - - items - title: WebhookHistoryByResourceDto - ProjectOverviewResponseDto: + title: DatasetListResponse + DeleteMonitorResponseDto: properties: - project_id: + success: + type: boolean + title: Success + description: True if the delete operation succeeded; false otherwise. + message: type: string - format: uuid - title: Project Id - description: Project identifier. - overview: - additionalProperties: - additionalProperties: - type: integer - type: object - type: object - title: Overview - description: Resource counts grouped by type. - type: object - required: - - project_id - - overview - title: ProjectOverviewResponseDto - AssignWebhookResourceRequestDto: - properties: - resource_type: - $ref: '#/components/schemas/MappableResourceType' - description: Type of resource to assign. - resource_id: - type: string - format: uuid - title: Resource Id - description: ID of the resource to assign. - type: object - required: - - resource_type - - resource_id - title: AssignWebhookResourceRequestDto - TestWebhookResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the test delivery succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - http_status_code: - anyOf: - - type: integer - - type: 'null' - title: Http Status Code - description: HTTP status code returned by the webhook endpoint. - response_body: - anyOf: - - {} - - type: 'null' - title: Response Body - description: Response body returned by the webhook endpoint. - type: object - required: - - success - - message - title: TestWebhookResponseDto - UpdateProjectResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project identifier. - type: object - required: - - success - - message - title: UpdateProjectResponseDto - AddResourceResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the overall operation succeeded. - message: - type: string - title: Message - description: Top-level result message. - results: - items: - $ref: '#/components/schemas/ResourceResultResponseDto' - type: array - title: Results - description: Per-resource outcome, one entry per submitted resource. + title: Message + description: Human-readable result message. + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: ID of the deleted monitor. Null on failure. type: object required: - success - message - title: AddResourceResponseDto - PullResponseDto: + title: DeleteMonitorResponseDto + SubmitRequestDto: properties: - job_id: - type: string - format: uuid - title: Job Id - description: UUID of the job. query: + type: string + minLength: 1 + title: Query + description: Natural-language question. Keywords and search queries are + extracted automatically. + schema: anyOf: - type: string - type: 'null' - title: Query - description: Original query submitted for this job. + title: Schema + description: 'Advanced: custom JSON schema string that overrides the default + extraction schema. Use POST /initialize to discover a suitable schema.' context: anyOf: - type: string - type: 'null' title: Context - description: Optional context provided at submission time. - validators: - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array - title: Validators - description: Validators applied to candidate articles. - default: [] - enrichments: - items: - $ref: '#/components/schemas/EnrichmentSchema' - type: array - title: Enrichments - description: Enrichment fields extracted per article. - default: [] - status: + description: Additional context to sharpen the search scope (geography, + industry, time frame, etc.). + limit: anyOf: - - $ref: '#/components/schemas/PublicJobStatus' + - type: integer + minimum: 10.0 - type: 'null' - description: Current pipeline stage. Results may be partial while status - != 'completed'. - error: + title: Limit + description: Maximum number of validated records to collect. Minimum 10. + Defaults to the plan limit. Use POST /continue to raise the limit later. + start_date: anyOf: - type: string + format: date-time - type: 'null' - title: Error - description: Human-readable error message. Present only when status == 'failed'. - duration: + title: Start Date + description: Earliest article date (ISO-8601 or free-text like '2024-01-01'). + If start_date is provided and end_date is omitted, end_date defaults to + now. + end_date: anyOf: - type: string + format: date-time - type: 'null' - title: Duration - description: Wall-clock processing time, e.g. '1m 23s'. - candidate_records: - anyOf: - - type: integer - - type: 'null' - title: Candidate Records - description: Total articles retrieved before validator filtering. - valid_records: - anyOf: - - type: integer - - type: 'null' - title: Valid Records - description: 'Articles that passed all validators. Invariant: valid_records - <= candidate_records. Equals candidate_records when no validators are - defined.' - progress_validated: - anyOf: - - type: integer - - type: 'null' - title: Progress Validated - description: Running count of validated records while status == 'enriching'. - date_range: + title: End Date + description: Latest article date. Cannot be provided without start_date. + validators: anyOf: - - $ref: '#/components/schemas/DateRangeDto' + - items: + $ref: '#/components/schemas/ValidatorSchema' + type: array - type: 'null' - description: Effective date range of the retrieved articles. - all_records: + title: Validators + description: Boolean classifiers. Only articles where every validator returns + true are counted in valid_records. Provide at least one item or omit entirely. + enrichments: anyOf: - items: - $ref: '#/components/schemas/ArticleRecordDto' + $ref: '#/components/schemas/EnrichmentSchema' type: array - type: 'null' - title: All Records - description: Paginated result records. Each record has a cluster identifier, - title, job-specific enrichment values, and source citations. - page: - type: integer - minimum: 1.0 - title: Page - description: Current page number (1-indexed). - default: 1 - page_size: - type: integer - minimum: 1.0 - title: Page Size - description: Number of records per page. - default: 10 - total_pages: - type: integer - minimum: 0.0 - title: Total Pages - description: Total pages available. - default: 0 - limit: + title: Enrichments + description: Custom extraction fields added to each result record under + enrichments.. Provide at least one item or omit entirely. + mode: anyOf: - - type: integer + - $ref: '#/components/schemas/ProcessingMode' - type: 'null' - title: Limit - description: Maximum records requested for this job. - mode: - $ref: '#/components/schemas/ProcessingMode' - description: 'Processing mode used: ''base'' or ''lite''.' + description: Processing mode. 'base' runs the full pipeline with clustering + and enrichment. 'lite' is faster with no clustering. default: base connected_dataset_ids: anyOf: @@ -3689,62 +3310,86 @@ components: type: array - type: 'null' title: Connected Dataset Ids - description: 'Deprecated: use connected_datasets instead. Dataset IDs that - were used to narrow retrieval scope.' - deprecated: true - connected_datasets: + description: IDs of datasets whose entities narrow the retrieval scope. + When provided, ed_score_min defaults to 2 if not specified. + ed_score_min: anyOf: - - items: - $ref: '#/components/schemas/ConnectedDatasetDto' - type: array + - type: integer + maximum: 10.0 + minimum: 1.0 - type: 'null' - title: Connected Datasets - description: Datasets used to narrow retrieval scope, each with id and name. - is_all_news_query: + title: Ed Score Min + description: Minimum entity-domain relevance score (1–10). Only relevant + when connected_dataset_ids is set. Defaults to 2. + ed_association_type: anyOf: - - type: boolean + - $ref: '#/components/schemas/EntityAssociationType' - type: 'null' - title: Is All News Query - description: True when the query was submitted as an all-news (watchlist-generic) - query. - source_groups: + description: 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. + webhook_ids: anyOf: - items: - $ref: '#/components/schemas/SourceGroupRefDto' + type: string + format: uuid type: array - type: 'null' - title: Source Groups - description: Source groups attached to this job, each with slug, name, and - description. - sharing_info: + title: Webhook Ids + description: Webhook IDs to notify when the job completes. Max 5 per job. + project_id: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string + format: uuid - type: 'null' - description: Present when the job was shared with the calling user (not - their own). - type: object - required: - - job_id - title: PullJobResponseDto - CreateEntitiesBatchRequestDto: - properties: - entities: - items: - $ref: '#/components/schemas/CreateEntityRequestDto' - type: array - title: Entities - description: Array of entities to create. + title: Project Id + description: Project ID to associate this job with. + fetch_all_watchlist_news: + type: boolean + title: Fetch All Watchlist News + description: When true, retrieves all news for connected Company Watchlist + entities without topic filtering. Requires connected_dataset_ids to be + set. + default: false + source_groups: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Source Groups + description: Slugs of source groups to scope fetching to their domain allowlists. + Fetch available source groups via GET /catchAll/source-groups. Max 20 + per job. type: object required: - - entities - title: CreateEntitiesBatchRequest + - query + title: SubmitRequestDto + example: + context: Focus on US-based companies with 500+ employees. + enrichments: + - description: The company conducting the layoffs. + name: company_name + type: company + - description: Number of employees affected, if mentioned. + name: employees_affected + type: number + limit: 100 + mode: base + query: Tech layoffs in 2024 + start_date: '2024-01-01T00:00:00Z' + validators: + - description: The article specifically covers workforce reductions or layoffs. + name: is_about_layoffs + type: boolean ListMonitorJobsResponseDto: properties: monitor_id: type: string format: uuid title: Monitor Id - description: Event monitor identifier. + description: Monitor identifier. sort_order: type: string title: Sort Order @@ -3752,20 +3397,71 @@ components: total_jobs: type: integer title: Total Jobs - description: Total number of jobs executed by this event monitor. + description: Total number of jobs executed by this monitor. jobs: items: $ref: '#/components/schemas/MonitorJobItemResponseDto' type: array title: Jobs - description: Array of event monitor job executions. + description: Array of monitor job executions. type: object required: - monitor_id - sort_order - total_jobs title: ListMonitorJobsResponseDto - CreateWebhookResponseDto: + EntityStatus: + type: string + enum: + - pending + - enriching + - ready + - failed + title: EntityStatus + description: 'Processing status of an entity: pending → enriching → ready. Failed + entities may still be used but matching quality may be reduced.' + ListDatasetEntitiesRequestDto: + properties: + page: + type: integer + minimum: 1.0 + title: Page + description: The page number to retrieve. + default: 1 + page_size: + type: integer + maximum: 500.0 + minimum: 1.0 + title: Page Size + description: The number of entities per page. + default: 100 + search: + anyOf: + - type: string + - type: 'null' + title: Search + description: Filters entities by name using case-insensitive substring match. + status: + anyOf: + - $ref: '#/components/schemas/EntityStatus' + - type: 'null' + description: Filter entities by processing status. + entity_type: + anyOf: + - $ref: '#/components/schemas/EntityType' + - type: 'null' + description: Filter entities by type. + sort_by: + $ref: '#/components/schemas/EntitySortBy' + description: Field to sort results by. + default: created_at + sort_order: + $ref: '#/components/schemas/SortOrder' + description: Sort direction. + default: desc + type: object + title: ListDatasetEntitiesRequest + EnableMonitorResponseDto: properties: success: type: boolean @@ -3774,225 +3470,254 @@ components: message: type: string title: Message - description: Human-readable result message. - webhook: + description: Human-readable success message. + monitor_id: anyOf: - - $ref: '#/components/schemas/WebhookResponseDto' + - type: string + format: uuid - type: 'null' - description: Created webhook details. + title: Monitor Id + description: ID of the enabled monitor. type: object required: - success - message - title: CreateWebhookResponseDto - DatasetStatusHistoryResponseDto: + title: EnableMonitorResponseDto + CsvUploadToExistingResponseDto: properties: dataset_id: type: string format: uuid title: Dataset Id - description: Dataset identifier. - history: - items: - $ref: '#/components/schemas/DatasetStatusEntryDto' - type: array - title: History - description: Status change entries, ordered oldest to newest. + description: ID of the dataset that was updated. + entities_created: + type: integer + title: Entities Created + description: Number of new entities created from the CSV. + validation_report: + $ref: '#/components/schemas/CsvValidationReportDto' + description: Summary of CSV processing results. type: object required: - dataset_id - - history - title: DatasetStatusHistoryResponse - EntityResponseDto: + - entities_created + - validation_report + title: UploadCsvToDatasetResponse + DatasetEntityListResponseDto: properties: - id: - type: string - format: uuid - title: Id - description: Unique identifier of the entity. - entity_type: - type: string - title: Entity Type - description: The type of entity. - organization_id: - type: string - title: Organization Id - description: Organization that owns this entity. - name: - type: string - title: Name - description: Entity name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Free-text description. - external_entity_id: - anyOf: - - type: string - - type: 'null' - title: External Entity Id - description: External identifier for this entity. Null when not set. - additional_attributes: - anyOf: - - $ref: '#/components/schemas/AdditionalAttributesDto' - - type: 'null' - description: Type-specific attributes. - status: - $ref: '#/components/schemas/EntityStatus' - description: Processing status of the entity. - created_by_user_id: - anyOf: - - type: string - - type: 'null' - title: Created By User Id - description: ID of the user who created this entity. - created_at: - anyOf: - - type: string - format: date-time - - type: 'null' - title: Created At - description: Timestamp of when the entity was created. - updated_at: - anyOf: - - type: string - format: date-time - - type: 'null' - title: Updated At - description: Timestamp of when the entity was last updated. + entities: + items: + $ref: '#/components/schemas/EntitySummaryDto' + type: array + title: Entities + description: Array of entity summary objects for this page. + total: + type: integer + title: Total + description: Total number of entities in the dataset. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of entities per page. type: object required: - - id - - entity_type - - organization_id - - name - - status - title: EntityResponse - EnableMonitorResponseDto: + - entities + - total + - page + - page_size + title: DatasetEntityListResponse + DeleteJobResponseDto: properties: success: type: boolean title: Success - description: True if the operation succeeded; false otherwise. + description: True if the delete operation succeeded; false otherwise. message: type: string title: Message - description: Human-readable success message. - monitor_id: + description: Human-readable result message. + job_id: anyOf: - type: string format: uuid - type: 'null' - title: Monitor Id - description: ID of the enabled event monitor. + title: Job Id + description: ID of the deleted job. Null on failure. type: object required: - success - message - title: EnableMonitorResponseDto - StatusResponseDto: + title: DeleteJobResponseDto + ManageEntitiesResponseDto: properties: - job_id: + dataset_id: type: string format: uuid - title: Job Id - description: UUID of the job. - example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - status: - anyOf: - - $ref: '#/components/schemas/PublicJobStatus' - - type: 'null' - description: 'Current pipeline stage. Poll until ''completed'' or ''failed''. - Recommended interval: 5 seconds.' - steps: - anyOf: - - items: - $ref: '#/components/schemas/JobStep' - type: array - - type: 'null' - title: Steps - description: Ordered pipeline stages with completion flags. Use to show - a progress bar to the user. + title: Dataset Id + description: ID of the dataset that was modified. + affected_count: + type: integer + title: Affected Count + description: Number of entities that were added or removed. type: object required: - - job_id - title: StatusResponseDto - EntityType: - type: string - enum: - - company - - person - title: EntityType - description: The type of entity. 'company' for organizations (default), 'person' - for individuals. - MonitorStatusHistoryResponseDto: + - dataset_id + - affected_count + title: ManageEntitiesResponse + WebhookHistoryByWebhookDto: properties: - success: - type: boolean - title: Success - description: True if the request succeeded; false otherwise. - message: + mode: + type: string + const: webhook + title: Mode + default: webhook + webhook_id: + type: string + format: uuid + title: Webhook Id + total: + type: integer + title: Total + page: + type: integer + title: Page + page_size: + type: integer + title: Page Size + items: + items: + $ref: '#/components/schemas/WebhookStatusItemDto' + type: array + title: Items + type: object + required: + - webhook_id + - total + - page + - page_size + - items + title: WebhookHistoryByWebhookDto + PullMonitorResponseDto: + properties: + monitor_id: + type: string + format: uuid + title: Monitor Id + description: Unique identifier for the monitor. + cron_expression: anyOf: - type: string - type: 'null' - title: Message - description: Optional message. Null on success. - monitor_id: + title: Cron Expression + description: Cron expression for the monitor schedule. + timezone: anyOf: - type: string - format: uuid - type: 'null' - title: Monitor Id - description: Event monitor identifier. Null on failure. - total_statuses: + title: Timezone + description: Timezone used for schedule execution. + reference_job: + $ref: '#/components/schemas/ReferenceJob' + description: Query and context from the reference job. + validators: + items: + $ref: '#/components/schemas/ValidatorSchema' + type: array + title: Validators + description: Validators applied to filter results. + enrichments: + items: + $ref: '#/components/schemas/EnrichmentSchema' + type: array + title: Enrichments + description: Enrichment fields used for data extraction. + run_info: + anyOf: + - $ref: '#/components/schemas/RunInfoDto' + - type: 'null' + description: Execution time range for this monitor. + records: anyOf: - type: integer - type: 'null' - title: Total Statuses - description: Total number of status entries in the history. - statuses: + title: Records + description: Total number of records collected across all monitor jobs. + status: + type: string + title: Status + description: Current monitor status or error message. + all_records: anyOf: - items: - $ref: '#/components/schemas/MonitorStatusEntryDto' + $ref: '#/components/schemas/MonitorRecordDto' type: array - type: 'null' - title: Statuses - description: Full status history, ordered newest to oldest. + title: All Records + description: Aggregated records from all jobs executed by this monitor. + limit: + anyOf: + - type: integer + - type: 'null' + title: Limit + description: Record limit applied to this monitor's jobs. + connected_datasets: + anyOf: + - items: + $ref: '#/components/schemas/ConnectedDatasetDto' + type: array + - type: 'null' + title: Connected Datasets + description: Datasets used to narrow retrieval scope, each with id and name. + is_all_news_query: + anyOf: + - type: boolean + - type: 'null' + title: Is All News Query + description: True when the reference job was submitted as an all-news (watchlist-generic) + query. + sharing_info: + anyOf: + - $ref: '#/components/schemas/SharingInfoDto' + - type: 'null' + description: Present when this monitor was shared with the authenticated + user. Omitted when the user owns the monitor. type: object required: - - success - title: MonitorStatusHistoryResponseDto - CreateProjectResponseDto: + - monitor_id + - reference_job + - status + title: PullMonitorResponseDto + AssignWebhookResourceResponseDto: properties: success: type: boolean title: Success description: True if the operation succeeded; false otherwise. message: - type: string - title: Message - description: Human-readable result message. - project_id: anyOf: - type: string - format: uuid - type: 'null' - title: Project Id - description: Project identifier. - name: + title: Message + description: Human-readable result message. + already_existed: + type: boolean + title: Already Existed + description: True if the mapping already existed. + default: false + mapping: anyOf: - - type: string + - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' - type: 'null' - title: Name - description: Name of the created project. + description: Created or existing resource mapping. type: object required: - success - - message - title: CreateProjectResponseDto - UpdateWebhookResponseDto: + title: AssignWebhookResourceResponseDto + UpdateProjectResponseDto: properties: success: type: boolean @@ -4002,108 +3727,253 @@ components: type: string title: Message description: Human-readable result message. - webhook: + project_id: anyOf: - - $ref: '#/components/schemas/WebhookResponseDto' + - type: string + format: uuid - type: 'null' - description: Updated webhook details. + title: Project Id + description: Project identifier. type: object required: - success - message - title: UpdateWebhookResponseDto - UpdateEntityRequestDto: + title: UpdateProjectResponseDto + CsvUploadCreateResponseDto: + properties: + dataset_id: + type: string + format: uuid + title: Dataset Id + description: Unique identifier of the created dataset. + dataset_name: + type: string + title: Dataset Name + description: Name of the created dataset. + entities_created: + type: integer + title: Entities Created + description: Number of entities successfully created from the CSV. + validation_report: + $ref: '#/components/schemas/CsvValidationReportDto' + description: Summary of CSV processing results. + type: object + required: + - dataset_id + - dataset_name + - entities_created + - validation_report + title: CreateDatasetCsvResponse + CreateEntityRequestDto: properties: name: - anyOf: - - type: string - - type: 'null' + type: string + minLength: 1 title: Name - description: Updated entity name. + description: Entity name. Required and must be non-empty. + entity_type: + type: string + title: Entity Type + description: The type of entity. + default: company description: anyOf: - type: string - type: 'null' title: Description - description: Updated description. + description: Free-text description for disambiguation. The entity must have + this or additional_attributes.company_attributes.domain set. external_entity_id: anyOf: - type: string maxLength: 255 - type: 'null' title: External Entity Id - description: Updated external identifier for this entity. + description: Optional external identifier for this entity. Free-form string, + not enforced as unique. additional_attributes: anyOf: - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - description: Updated type-specific attributes. - type: object - title: UpdateEntityRequest - ResourceListResponseDto: - properties: - total: - type: integer - title: Total - description: Total number of resources assigned to the project. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of resources per page. - total_pages: - type: integer - title: Total Pages - description: Total number of pages available. - resources: - items: - $ref: '#/components/schemas/ResourceItemResponseDto' - type: array - title: Resources - description: Resources on this page. + description: Type-specific attributes for the entity. type: object required: - - total - - page - - page_size - - total_pages - - resources - title: ProjectResourceListResponseDto - ListWebhooksResponseDto: + - name + title: CreateEntityRequest + CreateMonitorResponseDto: properties: - total: - type: integer - title: Total - description: Total number of webhooks. + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: Monitor identifier. Null if creation failed. + status: + type: string + title: Status + description: Creation status or error message. + default: Monitor Created Successfully + type: object + title: CreateMonitorResponseDto + PullResponseDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: UUID of the job. + query: + anyOf: + - type: string + - type: 'null' + title: Query + description: Original query submitted for this job. + context: + anyOf: + - type: string + - type: 'null' + title: Context + description: Optional context provided at submission time. + validators: + items: + $ref: '#/components/schemas/ValidatorSchema' + type: array + title: Validators + description: Validators applied to candidate articles. + default: [] + enrichments: + items: + $ref: '#/components/schemas/EnrichmentSchema' + type: array + title: Enrichments + description: Enrichment fields extracted per article. + default: [] + status: + anyOf: + - $ref: '#/components/schemas/PublicJobStatus' + - type: 'null' + description: Current pipeline stage. Results may be partial while status + != 'completed'. + error: + anyOf: + - type: string + - type: 'null' + title: Error + description: Human-readable error message. Present only when status == 'failed'. + duration: + anyOf: + - type: string + - type: 'null' + title: Duration + description: Wall-clock processing time, e.g. '1m 23s'. + candidate_records: + anyOf: + - type: integer + - type: 'null' + title: Candidate Records + description: Total articles retrieved before validator filtering. + valid_records: + anyOf: + - type: integer + - type: 'null' + title: Valid Records + description: 'Articles that passed all validators. Invariant: valid_records + <= candidate_records. Equals candidate_records when no validators are + defined.' + progress_validated: + anyOf: + - type: integer + - type: 'null' + title: Progress Validated + description: Running count of validated records while status == 'enriching'. + date_range: + anyOf: + - $ref: '#/components/schemas/DateRangeDto' + - type: 'null' + description: Effective date range of the retrieved articles. + all_records: + anyOf: + - items: + $ref: '#/components/schemas/ArticleRecordDto' + type: array + - type: 'null' + title: All Records + description: Paginated result records. Each record has a cluster identifier, + title, job-specific enrichment values, and source citations. page: type: integer + minimum: 1.0 title: Page - description: Current page number. + description: Current page number (1-indexed). + default: 1 page_size: type: integer + minimum: 1.0 title: Page Size - description: Number of webhooks per page. + description: Number of records per page. + default: 10 total_pages: type: integer + minimum: 0.0 title: Total Pages - description: Total number of pages available. - webhooks: - items: - $ref: '#/components/schemas/WebhookResponseDto' - type: array - title: Webhooks - description: Array of webhook objects on this page. + description: Total pages available. + default: 0 + limit: + anyOf: + - type: integer + - type: 'null' + title: Limit + description: Maximum records requested for this job. + mode: + $ref: '#/components/schemas/ProcessingMode' + description: 'Processing mode used: ''base'' or ''lite''.' + default: base + connected_dataset_ids: + anyOf: + - items: + type: string + format: uuid + type: array + - type: 'null' + title: Connected Dataset Ids + description: 'Deprecated: use connected_datasets instead. Dataset IDs that + were used to narrow retrieval scope.' + deprecated: true + connected_datasets: + anyOf: + - items: + $ref: '#/components/schemas/ConnectedDatasetDto' + type: array + - type: 'null' + title: Connected Datasets + description: Datasets used to narrow retrieval scope, each with id and name. + is_all_news_query: + anyOf: + - type: boolean + - type: 'null' + title: Is All News Query + description: True when the query was submitted as an all-news (watchlist-generic) + query. + source_groups: + anyOf: + - items: + $ref: '#/components/schemas/SourceGroupRefDto' + type: array + - type: 'null' + title: Source Groups + description: Source groups attached to this job, each with slug, name, and + description. + sharing_info: + anyOf: + - $ref: '#/components/schemas/SharingInfoDto' + - type: 'null' + description: Present when the job was shared with the calling user (not + their own). type: object required: - - total - - page - - page_size - - total_pages - - webhooks - title: ListWebhooksResponseDto + - job_id + title: PullJobResponseDto ListUserJobsResponseDto: properties: total: @@ -4136,111 +4006,235 @@ components: - total_pages - jobs title: ListUserJobsResponseDto - CreateMonitorRequestDto: + CreateEntitiesBatchResponseDto: properties: - reference_job_id: - type: string - format: uuid - title: Reference Job Id - description: ID of a completed job whose query/validators/enrichments this - event monitor should repeat. - example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - schedule: + entities: + items: + $ref: '#/components/schemas/CreateEntityResponseDto' + type: array + title: Entities + description: Array of created entity stubs in the same order as the input. + count: + type: integer + title: Count + description: Total number of entities created. + type: object + required: + - entities + - count + title: CreateEntitiesBatchResponse + EntitySortBy: + type: string + enum: + - created_at + - name + - status + title: EntitySortBy + description: Fields available for sorting entity list results. + MappableResourceType: + type: string + enum: + - job + - monitor + - monitor_group + title: MappableResourceType + description: 'Resource types that can be assigned to a webhook: job, monitor, + or monitor_group.' + UpdateWebhookResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: type: string - title: Schedule - description: 'Natural-language schedule string converted to a cron expression. - Examples: ''every day at 9 AM'', ''every Monday at 6 PM EST''. An inline - timezone in the text overrides the timezone field.' - example: every day at 9 AM - timezone: - anyOf: - - type: string - - type: 'null' - title: Timezone - description: IANA timezone for the schedule (e.g. 'America/New_York'). Overridden - if the schedule text itself contains a timezone. - default: UTC - example: America/New_York - webhook_ids: + title: Message + description: Human-readable result message. + webhook: anyOf: - - items: - type: string - format: uuid - type: array + - $ref: '#/components/schemas/WebhookResponseDto' - type: 'null' - title: Webhook Ids - description: Webhook IDs to notify on each run completion. Max 5 per event monitor. - limit: + description: Updated webhook details. + type: object + required: + - success + - message + title: UpdateWebhookResponseDto + DatasetStatus: + type: string + enum: + - pending + - enriching + - ready + - failed + title: DatasetStatus + description: 'Processing status of a dataset: pending → enriching → ready. Failed + indicates one or more entity enrichments failed.' + EntityType: + type: string + enum: + - company + - person + title: EntityType + description: The type of entity. 'company' for organizations (default), 'person' + for individuals. + UpdateDatasetRequestDto: + properties: + name: anyOf: - - type: integer - minimum: 10.0 + - type: string - type: 'null' - title: Limit - description: Max results per event monitor run. Minimum 10. Validated against - plan limit. - example: 50 + title: Name + description: Updated dataset name. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Updated description. + type: object + title: UpdateDatasetRequest + CreateProjectRequestDto: + properties: + name: + type: string + title: Name + description: Name for the project. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Optional description. + type: object + required: + - name + title: CreateProjectRequestDto + EnableMonitorRequestDto: + properties: backfill: anyOf: - type: boolean - type: 'null' title: Backfill - description: If true, the first run chains forward from the reference job's - end date (enforces a 7-day lookback check). If false, the first run uses - the current cron window. + description: If True, enforce lookback check on last job; if False, skip + date check. default: true - project_id: + type: object + title: EnableMonitorRequestDto + description: Optional body for POST /{monitor_id}/enable. + UpdateWebhookRequestDto: + properties: + name: anyOf: - type: string - format: uuid - type: 'null' - title: Project Id - description: Project to associate this event monitor with. + title: Name + description: Updated webhook name. + url: + anyOf: + - type: string + - type: 'null' + title: Url + description: Updated webhook endpoint URL. + type: + anyOf: + - $ref: '#/components/schemas/WebhookType' + - type: 'null' + description: Updated webhook target type. + delivery_mode: + anyOf: + - $ref: '#/components/schemas/DeliveryMode' + - type: 'null' + description: Updated delivery mode. + method: + anyOf: + - $ref: '#/components/schemas/HttpMethod' + - type: 'null' + description: Updated HTTP method. + headers: + anyOf: + - additionalProperties: + type: string + type: object + - type: 'null' + title: Headers + description: Updated HTTP headers. + params: + anyOf: + - additionalProperties: + type: string + type: object + - type: 'null' + title: Params + description: Updated query string parameters. + auth: + anyOf: + - oneOf: + - $ref: '#/components/schemas/BearerAuthDto' + - $ref: '#/components/schemas/ApiKeyAuthDto' + - $ref: '#/components/schemas/BasicAuthDto' + discriminator: + propertyName: type + mapping: + api_key: '#/components/schemas/ApiKeyAuthDto' + basic: '#/components/schemas/BasicAuthDto' + bearer: '#/components/schemas/BearerAuthDto' + - type: 'null' + title: Auth + description: 'Authentication forwarded with each delivery. Supported types: + ''bearer'' (token), ''api_key'' (header + value), ''basic'' (username + + password).' + formatter_config: + anyOf: + - $ref: '#/components/schemas/FormatterConfigDto' + - type: 'null' + description: Updated custom formatter configuration. + is_active: + anyOf: + - type: boolean + - type: 'null' + title: Is Active + description: Set to true to activate or false to deactivate. type: object - required: - - reference_job_id - - schedule - title: CreateMonitorRequestDto - DatasetSortBy: - type: string - enum: - - name - - created_at - - status - title: DatasetSortBy - description: Fields available for sorting dataset list results. - ManageEntitiesResponseDto: + title: UpdateWebhookRequestDto + RemoveResourceResponseDto: properties: - dataset_id: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: type: string - format: uuid - title: Dataset Id - description: ID of the dataset that was modified. - affected_count: - type: integer - title: Affected Count - description: Number of entities that were added or removed. + title: Message + description: Human-readable result message. type: object required: - - dataset_id - - affected_count - title: ManageEntitiesResponse - TestWebhookRequestDto: + - success + - message + title: RemoveResourceResponseDto + UpdateProjectRequestDto: properties: - payload: + name: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Payload - description: Custom payload to send in the test request. + title: Name + description: New name for the project. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: New description for the project. type: object - title: TestWebhookRequestDto - ListWebhookResourcesResponseDto: + title: UpdateProjectRequestDto + ListWebhooksForResourceResponseDto: properties: total: type: integer title: Total - description: Total number of resource mappings. + description: Total number of webhooks assigned to this resource. page: type: integer title: Page @@ -4248,200 +4242,410 @@ components: page_size: type: integer title: Page Size - description: Number of mappings per page. + description: Number of webhooks per page. total_pages: type: integer title: Total Pages description: Total number of pages available. - resources: + webhooks: items: - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' + $ref: '#/components/schemas/WebhookResponseDto' type: array - title: Resources - description: Array of resource mappings on this page. + title: Webhooks + description: Array of webhook objects. type: object required: - total - page - page_size - total_pages - - resources - title: ListWebhookResourcesResponseDto - PullMonitorResponseDto: + - webhooks + title: ListWebhooksForResourceResponseDto + SubmitResponseDto: properties: - monitor_id: + job_id: type: string format: uuid - title: Monitor Id - description: Unique identifier for the event monitor. - cron_expression: + title: Job Id + description: UUID of the created job. Use this in /status and /pull. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + type: object + required: + - job_id + title: SubmitResponseDto + UpdateMonitorRequestDto: + properties: + webhook_ids: + anyOf: + - items: + type: string + format: uuid + type: array + - type: 'null' + title: Webhook Ids + description: Optional list of centralized webhook IDs to assign to this + monitor. Empty list clears assignments. + limit: + anyOf: + - type: integer + - type: 'null' + title: Limit + description: Optional max results per monitor run (min 10, validated against + plan) + schedule: anyOf: - type: string - type: 'null' - title: Cron Expression - description: Cron expression for the event monitor schedule. + title: Schedule + description: 'New natural-language schedule to replace the monitor''s current + one. Examples: ''every day at 9 AM'', ''every Monday at 6 PM EST''. Leave + unset to keep the current schedule. The scheduler picks up the new cron + expression on its next reload and the old schedule stops firing.' + example: every day at 9 AM timezone: anyOf: - type: string - type: 'null' title: Timezone - description: Timezone used for schedule execution. - reference_job: - $ref: '#/components/schemas/ReferenceJob' - description: Query and context from the reference job. - validators: - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array - title: Validators - description: Validators applied to filter results. - enrichments: - items: - $ref: '#/components/schemas/EnrichmentSchema' - type: array - title: Enrichments - description: Enrichment fields used for data extraction. - run_info: + description: IANA timezone for the new schedule (e.g. 'America/New_York'). + Overridden if the schedule text itself contains a timezone. Ignored if + `schedule` is not set. + default: UTC + example: America/New_York + type: object + title: UpdateMonitorRequestDto + DatasetSortBy: + type: string + enum: + - name + - created_at + - status + title: DatasetSortBy + description: Fields available for sorting dataset list results. + StatusResponseDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: UUID of the job. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + status: anyOf: - - $ref: '#/components/schemas/RunInfoDto' + - $ref: '#/components/schemas/PublicJobStatus' - type: 'null' - description: Execution time range for this event monitor. - records: + description: 'Current pipeline stage. Poll until ''completed'' or ''failed''. + Recommended interval: 5 seconds.' + steps: anyOf: - - type: integer + - items: + $ref: '#/components/schemas/JobStep' + type: array - type: 'null' - title: Records - description: Total number of records collected across all event monitor jobs. + title: Steps + description: Ordered pipeline stages with completion flags. Use to show + a progress bar to the user. + type: object + required: + - job_id + title: StatusResponseDto + DisableMonitorResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable success message. + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: ID of the disabled monitor. + type: object + required: + - success + - message + title: DisableMonitorResponseDto + CreateEntityResponseDto: + properties: + id: + type: string + format: uuid + title: Id + description: Unique identifier of the created entity. status: type: string title: Status - description: Current event monitor status or error message. - all_records: + description: Initial status of the entity. Always pending immediately after + creation. + default: pending + type: object + required: + - id + title: CreateEntityResponse + CreateDatasetRequestDto: + properties: + name: + type: string + minLength: 1 + title: Name + description: Name for the dataset. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Optional description. + entity_ids: anyOf: - items: - $ref: '#/components/schemas/MonitorRecordDto' + type: string + format: uuid type: array - type: 'null' - title: All Records - description: Aggregated records from all jobs executed by this event monitor. - limit: + title: Entity Ids + description: IDs of existing entities to include in the dataset. + project_id: anyOf: - - type: integer + - type: string + format: uuid - type: 'null' - title: Limit - description: Record limit applied to this event monitor's jobs. - connected_datasets: + title: Project Id + description: Project to assign this dataset to. + type: object + required: + - name + title: CreateDatasetRequest + CreateMonitorRequestDto: + properties: + reference_job_id: + type: string + format: uuid + title: Reference Job Id + description: ID of a completed job whose query/validators/enrichments this + monitor should repeat. + example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + schedule: + type: string + title: Schedule + description: 'Natural-language schedule string converted to a cron expression. + Examples: ''every day at 9 AM'', ''every Monday at 6 PM EST''. An inline + timezone in the text overrides the timezone field.' + example: every day at 9 AM + timezone: + anyOf: + - type: string + - type: 'null' + title: Timezone + description: IANA timezone for the schedule (e.g. 'America/New_York'). Overridden + if the schedule text itself contains a timezone. + default: UTC + example: America/New_York + webhook_ids: anyOf: - items: - $ref: '#/components/schemas/ConnectedDatasetDto' + type: string + format: uuid type: array - type: 'null' - title: Connected Datasets - description: Datasets used to narrow retrieval scope, each with id and name. - is_all_news_query: + title: Webhook Ids + description: Webhook IDs to notify on each run completion. Max 5 per monitor. + limit: + anyOf: + - type: integer + minimum: 10.0 + - type: 'null' + title: Limit + description: Max results per monitor run. Minimum 10. Validated against + plan limit. + example: 50 + backfill: anyOf: - type: boolean - type: 'null' - title: Is All News Query - description: True when the reference job was submitted as an all-news (watchlist-generic) - query. - sharing_info: + title: Backfill + description: If true, the first run chains forward from the reference job's + end date (enforces a 7-day lookback check). If false, the first run uses + the current cron window. + default: true + project_id: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string + format: uuid - type: 'null' - description: Present when this event monitor was shared with the authenticated - user. Omitted when the user owns the event monitor. + title: Project Id + description: Project to associate this monitor with. type: object required: - - monitor_id - - reference_job - - status - title: PullMonitorResponseDto - CreateEntityRequestDto: + - reference_job_id + - schedule + title: CreateMonitorRequestDto + UpdateEntityRequestDto: properties: name: - type: string - minLength: 1 + anyOf: + - type: string + - type: 'null' title: Name - description: Entity name. Required and must be non-empty. - entity_type: - type: string - title: Entity Type - description: The type of entity. - default: company + description: Updated entity name. description: anyOf: - type: string - type: 'null' title: Description - description: Free-text description for disambiguation. The entity must have - this or additional_attributes.company_attributes.domain set. + description: Updated description. external_entity_id: anyOf: - type: string maxLength: 255 - type: 'null' title: External Entity Id - description: Optional external identifier for this entity. Free-form string, - not enforced as unique. + description: Updated external identifier for this entity. additional_attributes: anyOf: - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - description: Type-specific attributes for the entity. + description: Updated type-specific attributes. + type: object + title: UpdateEntityRequest + ContinueRequestDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: Existing job to extend with a higher result limit. + new_limit: + anyOf: + - type: integer + - type: 'null' + title: New Limit + description: New limit, must be greater than the current limit. If null, + raises to the plan maximum. + example: 250 type: object required: - - name - title: CreateEntityRequest - SortOrder: - type: string - enum: - - asc - - desc - title: SortOrder - description: Sort direction for list results. 'asc' for ascending (oldest first), - 'desc' for descending (newest first). - DatasetListResponseDto: + - job_id + title: ContinueRequestDto + example: + job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + new_limit: 250 + DatasetStatusHistoryResponseDto: properties: - datasets: + dataset_id: + type: string + format: uuid + title: Dataset Id + description: Dataset identifier. + history: items: - $ref: '#/components/schemas/DatasetResponseDto' + $ref: '#/components/schemas/DatasetStatusEntryDto' type: array - title: Datasets - description: Array of dataset objects for this page. - total: - type: integer - title: Total - description: Total number of datasets matching the filter criteria. - page: - type: integer - title: Page + title: History + description: Status change entries, ordered oldest to newest. + type: object + required: + - dataset_id + - history + title: DatasetStatusHistoryResponse + Body_uploadCSVToDataset: + properties: + file: + type: string + format: binary + title: File + type: object + required: + - file + title: Body_uploadCSVToDataset + EntityListResponseDto: + properties: + entities: + items: + $ref: '#/components/schemas/EntityResponseDto' + type: array + title: Entities + description: Array of entity objects for this page. + total: + type: integer + title: Total + description: Total number of entities matching the filter criteria. + page: + type: integer + title: Page description: Current page number. page_size: type: integer title: Page Size - description: Number of datasets per page. + description: Number of entities per page. type: object required: - - datasets + - entities - total - page - page_size - title: DatasetListResponse - ProcessingMode: - type: string - enum: - - base - - lite - title: ProcessingMode - description: Job processing mode. 'base' runs the full pipeline with clustering - and enrichment. 'lite' is a faster mode that skips clustering. - ListMonitorsResponseDto: + title: EntityListResponse + DatasetEntityIdsRequestDto: + properties: + entity_ids: + items: + type: string + format: uuid + type: array + title: Entity Ids + description: List of entity IDs to add or remove. + type: object + required: + - entity_ids + title: DatasetEntityIdsRequest + UpdateMonitorResponseDto: + properties: + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: Monitor identifier. + status: + type: string + title: Status + description: Confirmation message. + default: Monitor updated Successfully + type: object + title: UpdateMonitorResponseDto + AddResourceResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the overall operation succeeded. + message: + type: string + title: Message + description: Top-level result message. + results: + items: + $ref: '#/components/schemas/ResourceResultResponseDto' + type: array + title: Results + description: Per-resource outcome, one entry per submitted resource. + type: object + required: + - success + - message + title: AddResourceResponseDto + ListWebhooksResponseDto: properties: total: type: integer title: Total - description: Total number of event monitors for this user. + description: Total number of webhooks. page: type: integer title: Page @@ -4449,25 +4653,72 @@ components: page_size: type: integer title: Page Size - description: Number of event monitors per page. + description: Number of webhooks per page. total_pages: type: integer title: Total Pages description: Total number of pages available. - monitors: + webhooks: items: - $ref: '#/components/schemas/MonitorListItemResponseDto' + $ref: '#/components/schemas/WebhookResponseDto' type: array - title: Monitors - description: Array of event monitor summaries. + title: Webhooks + description: Array of webhook objects on this page. type: object required: - total - page - page_size - total_pages - - monitors - title: ListMonitorsResponseDto + - webhooks + title: ListWebhooksResponseDto + ContinueResponseDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: UUID of the continued job. + previous_limit: + anyOf: + - type: integer + - type: 'null' + title: Previous Limit + description: The limit before this continue request. + new_limit: + type: integer + title: New Limit + description: The new limit now in effect. + status: + type: string + title: Status + description: Always 'accepted' on success. + default: accepted + type: object + required: + - job_id + - new_limit + title: ContinueResponseDto + ProjectOverviewResponseDto: + properties: + project_id: + type: string + format: uuid + title: Project Id + description: Project identifier. + overview: + additionalProperties: + additionalProperties: + type: integer + type: object + type: object + title: Overview + description: Resource counts grouped by type. + type: object + required: + - project_id + - overview + title: ProjectOverviewResponseDto DatasetResponseDto: properties: id: @@ -4550,220 +4801,121 @@ components: - organization_id - name title: DatasetResponse - ListSourceGroupsApiResponseDto: + CreateWebhookResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable result message. + webhook: + anyOf: + - $ref: '#/components/schemas/WebhookResponseDto' + - type: 'null' + description: Created webhook details. + type: object + required: + - success + - message + title: CreateWebhookResponseDto + ListWebhookResourcesResponseDto: properties: - source_groups: - items: - $ref: '#/components/schemas/SourceGroupApiResponseDto' - type: array - title: Source Groups total: type: integer title: Total + description: Total number of resource mappings. page: type: integer title: Page + description: Current page number. page_size: type: integer title: Page Size + description: Number of mappings per page. + total_pages: + type: integer + title: Total Pages + description: Total number of pages available. + resources: + items: + $ref: '#/components/schemas/WebhookResourceMappingResponseDto' + type: array + title: Resources + description: Array of resource mappings on this page. type: object required: - - source_groups - total - page - page_size - title: ListSourceGroupsApiResponseDto - Body_createDatasetFromCsv: + - total_pages + - resources + title: ListWebhookResourcesResponseDto + GetProjectResponseDto: properties: - file: - type: string - format: binary - title: File - name: - type: string - title: Name - description: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: type: string - title: Description + title: Message + description: Human-readable result message. project_id: - type: string + anyOf: + - type: string + format: uuid + - type: 'null' title: Project Id - type: object - required: - - file - - name - title: Body_createDatasetFromCsv - UpdateDatasetRequestDto: - properties: + description: Project identifier. name: anyOf: - type: string - type: 'null' title: Name - description: Updated dataset name. + description: Project name. description: anyOf: - type: string - type: 'null' title: Description - description: Updated description. - type: object - title: UpdateDatasetRequest - UpdateWebhookRequestDto: - properties: - name: + description: Project description. + resources_count: + type: integer + title: Resources Count + description: Number of resources assigned to this project. + default: 0 + created_at: anyOf: - type: string - type: 'null' - title: Name - description: Updated webhook name. - url: + title: Created At + description: Project creation timestamp. + updated_at: anyOf: - type: string - type: 'null' - title: Url - description: Updated webhook endpoint URL. - type: - anyOf: - - $ref: '#/components/schemas/WebhookType' - - type: 'null' - description: Updated webhook target type. - delivery_mode: - anyOf: - - $ref: '#/components/schemas/DeliveryMode' - - type: 'null' - description: Updated delivery mode. - method: - anyOf: - - $ref: '#/components/schemas/HttpMethod' - - type: 'null' - description: Updated HTTP method. - headers: - anyOf: - - additionalProperties: - type: string - type: object - - type: 'null' - title: Headers - description: Updated HTTP headers. - params: - anyOf: - - additionalProperties: - type: string - type: object - - type: 'null' - title: Params - description: Updated query string parameters. - auth: - anyOf: - - oneOf: - - $ref: '#/components/schemas/BearerAuthDto' - - $ref: '#/components/schemas/ApiKeyAuthDto' - - $ref: '#/components/schemas/BasicAuthDto' - discriminator: - propertyName: type - mapping: - api_key: '#/components/schemas/ApiKeyAuthDto' - basic: '#/components/schemas/BasicAuthDto' - bearer: '#/components/schemas/BearerAuthDto' - - type: 'null' - title: Auth - description: 'Authentication forwarded with each delivery. Supported types: - ''bearer'' (token), ''api_key'' (header + value), ''basic'' (username - + password).' - formatter_config: - anyOf: - - $ref: '#/components/schemas/FormatterConfigDto' - - type: 'null' - description: Updated custom formatter configuration. - is_active: + title: Updated At + description: Timestamp of the last update. + sharing_info: anyOf: - - type: boolean + - $ref: '#/components/schemas/SharingInfoDto' - type: 'null' - title: Is Active - description: Set to true to activate or false to deactivate. - type: object - title: UpdateWebhookRequestDto - WebhookHistoryByWebhookDto: - properties: - mode: - type: string - const: webhook - title: Mode - default: webhook - webhook_id: - type: string - format: uuid - title: Webhook Id - total: - type: integer - title: Total - page: - type: integer - title: Page - page_size: - type: integer - title: Page Size - items: - items: - $ref: '#/components/schemas/WebhookStatusItemDto' - type: array - title: Items + description: Present when this project was shared with the authenticated + user. type: object required: - - webhook_id - - total - - page - - page_size - - items - title: WebhookHistoryByWebhookDto - ListDatasetEntitiesRequestDto: - properties: - page: - type: integer - minimum: 1.0 - title: Page - description: The page number to retrieve. - default: 1 - page_size: - type: integer - maximum: 500.0 - minimum: 1.0 - title: Page Size - description: The number of entities per page. - default: 100 - search: - anyOf: - - type: string - - type: 'null' - title: Search - description: Filters entities by name using case-insensitive substring match. - status: - anyOf: - - $ref: '#/components/schemas/EntityStatus' - - type: 'null' - description: Filter entities by processing status. - entity_type: - anyOf: - - $ref: '#/components/schemas/EntityType' - - type: 'null' - description: Filter entities by type. - sort_by: - $ref: '#/components/schemas/EntitySortBy' - description: Field to sort results by. - default: created_at - sort_order: - $ref: '#/components/schemas/SortOrder' - description: Sort direction. - default: desc - type: object - title: ListDatasetEntitiesRequest - ProjectListResponseDto: + - success + - message + title: GetProjectResponseDto + ListMonitorsResponseDto: properties: total: type: integer title: Total - description: Total number of projects matching the filter criteria. + description: Total number of monitors for this user. page: type: integer title: Page @@ -4771,73 +4923,55 @@ components: page_size: type: integer title: Page Size - description: Number of projects per page. + description: Number of monitors per page. total_pages: type: integer title: Total Pages description: Total number of pages available. - projects: + monitors: items: - $ref: '#/components/schemas/ProjectResponseDto' + $ref: '#/components/schemas/MonitorListItemResponseDto' type: array - title: Projects - description: Projects on this page. + title: Monitors + description: Array of monitor summaries. type: object required: - total - page - page_size - total_pages - - projects - title: ProjectListResponseDto - ContinueResponseDto: + - monitors + title: ListMonitorsResponseDto + TestWebhookRequestDto: properties: - job_id: - type: string - format: uuid - title: Job Id - description: UUID of the continued job. - previous_limit: + payload: anyOf: - - type: integer + - additionalProperties: true + type: object - type: 'null' - title: Previous Limit - description: The limit before this continue request. - new_limit: - type: integer - title: New Limit - description: The new limit now in effect. - status: - type: string - title: Status - description: Always 'accepted' on success. - default: accepted - type: object - required: - - job_id - - new_limit - title: ContinueResponseDto - CsvUploadToExistingResponseDto: - properties: - dataset_id: - type: string - format: uuid - title: Dataset Id - description: ID of the dataset that was updated. - entities_created: - type: integer - title: Entities Created - description: Number of new entities created from the CSV. - validation_report: - $ref: '#/components/schemas/CsvValidationReportDto' - description: Summary of CSV processing results. + title: Payload + description: Custom payload to send in the test request. type: object - required: - - dataset_id - - entities_created - - validation_report - title: UploadCsvToDatasetResponse - DisableMonitorResponseDto: + title: TestWebhookRequestDto + ProjectResourceTypeEnum: + type: string + enum: + - job + - monitor + - dataset + - monitor_group + - webhook + title: ProjectResourceTypeEnum + description: Resource type for project association. + ProcessingMode: + type: string + enum: + - base + - lite + title: ProcessingMode + description: Job processing mode. 'base' runs the full pipeline with clustering + and enrichment. 'lite' is a faster mode that skips clustering. + DeleteProjectResponseDto: properties: success: type: boolean @@ -4846,27 +4980,94 @@ components: message: type: string title: Message - description: Human-readable success message. - monitor_id: + description: Human-readable result message. + project_id: anyOf: - type: string format: uuid - type: 'null' - title: Monitor Id - description: ID of the disabled event monitor. + title: Project Id + description: ID of the deleted project. + deleted_resources: + anyOf: + - additionalProperties: + type: integer + type: object + - type: 'null' + title: Deleted Resources + description: Count of deleted resources grouped by type (job, monitor, dataset, + monitor_group). Includes a 'webhook_unlinked' count for webhooks that + were detached from the project (not deleted) as part of this operation + — webhooks are never deleted when a project is deleted, since a webhook + may be attached to other resources independently of this project. type: object required: - success - message - title: DisableMonitorResponseDto - SuggestInitializeRequestDto: + title: DeleteProjectResponseDto + CreateProjectResponseDto: properties: - query: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: type: string - title: Query - description: Natural-language question to analyse. The API returns the validators - and enrichments it would auto-generate for this query. - example: Which airlines expanded their routes in Asia? + title: Message + description: Human-readable result message. + project_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Project Id + description: Project identifier. + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Name of the created project. + type: object + required: + - success + - message + title: CreateProjectResponseDto + TestWebhookResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the test delivery succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable result message. + http_status_code: + anyOf: + - type: integer + - type: 'null' + title: Http Status Code + description: HTTP status code returned by the webhook endpoint. + response_body: + anyOf: + - {} + - type: 'null' + title: Response Body + description: Response body returned by the webhook endpoint. + type: object + required: + - success + - message + title: TestWebhookResponseDto + SuggestInitializeRequestDto: + properties: + query: + type: string + title: Query + description: Natural-language question to analyse. The API returns the validators + and enrichments it would auto-generate for this query. + example: Which airlines expanded their routes in Asia? context: anyOf: - type: string @@ -4898,235 +5099,95 @@ components: example: context: Focus on low-cost carriers. query: Which airlines expanded their routes in Asia? - CsvUploadCreateResponseDto: + AssignWebhookResourceRequestDto: properties: - dataset_id: + resource_type: + $ref: '#/components/schemas/MappableResourceType' + description: Type of resource to assign. + resource_id: type: string format: uuid - title: Dataset Id - description: Unique identifier of the created dataset. - dataset_name: - type: string - title: Dataset Name - description: Name of the created dataset. - entities_created: - type: integer - title: Entities Created - description: Number of entities successfully created from the CSV. - validation_report: - $ref: '#/components/schemas/CsvValidationReportDto' - description: Summary of CSV processing results. - type: object - required: - - dataset_id - - dataset_name - - entities_created - - validation_report - title: CreateDatasetCsvResponse - DeleteProjectResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: ID of the deleted project. - deleted_resources: - anyOf: - - additionalProperties: - type: integer - type: object - - type: 'null' - title: Deleted Resources - description: Count of deleted resources grouped by type (job, event monitor, dataset, - event monitor group). Includes a 'webhook_unlinked' count for webhooks that - were detached from the project (not deleted) as part of this operation - — webhooks are never deleted when a project is deleted, since a webhook - may be attached to other resources independently of this project. + title: Resource Id + description: ID of the resource to assign. type: object required: - - success - - message - title: DeleteProjectResponseDto - DatasetEntityListResponseDto: + - resource_type + - resource_id + title: AssignWebhookResourceRequestDto + SortOrder: + type: string + enum: + - asc + - desc + title: SortOrder + description: Sort direction for list results. 'asc' for ascending (oldest first), + 'desc' for descending (newest first). + AddResourceRequestDto: properties: - entities: + resources: items: - $ref: '#/components/schemas/EntitySummaryDto' + $ref: '#/components/schemas/ResourceItemRequestDto' type: array - title: Entities - description: Array of entity summary objects for this page. - total: - type: integer - title: Total - description: Total number of entities in the dataset. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of entities per page. + title: Resources + description: Resources to assign to the project. type: object required: - - entities - - total - - page - - page_size - title: DatasetEntityListResponse - SuggestInitializeResponseDto: + - resources + title: AddResourceRequestDto + GetFeaturesResponse: properties: - query: - type: string - title: Query - description: Echo of the query from the request. - context: - anyOf: - - type: string - - type: 'null' - title: Context - description: Echo of the context from the request. Null if not provided. - start_date: - anyOf: - - type: string - format: date-time - - type: 'null' - title: Start Date - description: Suggested start date for web search in ISO 8601 format. - end_date: - anyOf: - - type: string - format: date-time - - type: 'null' - title: End Date - description: Suggested end date for web search in ISO 8601 format. - validators: - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array - title: Validators - description: Suggested validators for filtering relevant web pages. - enrichments: + features: items: - $ref: '#/components/schemas/EnrichmentSchema' + $ref: '#/components/schemas/BillingFeatureWithUsage' type: array - title: Enrichments - description: Suggested enrichment fields for data extraction. - date_modification_message: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Date Modification Message - description: Messages explaining date adjustments due to plan limits. + title: Features + description: Plan features with current usage. type: object required: - - query - title: InitializeResponseDto - Ownership: + - features + title: GetPlanLimitsResponseDto + IssueType: type: string enum: - - all - - own - - shared - title: Ownership - description: Controls which resources are returned based on ownership. 'all' - returns owned and shared resources, 'own' returns only user-created resources, - 'shared' returns only resources shared by others. - DeleteJobResponseDto: + - missing_event_type + - too_vague + - too_specific + - wrong_timeframe + - static_content + - article_request + - multiple_event_types + - too_short + - too_long + title: IssueType + description: Specific categories of query issues + QueryStatus: + type: string + enum: + - good + - needs_work + - critical + title: QueryStatus + description: Query quality assessment levels + Suggestion: properties: - success: - type: boolean - title: Success - description: True if the delete operation succeeded; false otherwise. + issue: + $ref: '#/components/schemas/IssueType' message: type: string title: Message - description: Human-readable result message. - job_id: + description: Clear, specific guidance + example: anyOf: - type: string - format: uuid - type: 'null' - title: Job Id - description: ID of the deleted job. Null on failure. + title: Example + description: Example of improved query type: object required: - - success + - issue - message - title: DeleteJobResponseDto - CreateMonitorResponseDto: - properties: - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: Event monitor identifier. Null if creation failed. - status: - type: string - title: Status - description: Creation status or error message. - default: Monitor Created Successfully - type: object - title: CreateMonitorResponseDto - CreateDatasetRequestDto: - properties: - name: - type: string - minLength: 1 - title: Name - description: Name for the dataset. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Optional description. - entity_ids: - anyOf: - - items: - type: string - format: uuid - type: array - - type: 'null' - title: Entity Ids - description: IDs of existing entities to include in the dataset. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project to assign this dataset to. - type: object - required: - - name - title: CreateDatasetRequest - GetFeaturesResponse: - properties: - features: - items: - $ref: '#/components/schemas/BillingFeatureWithUsage' - type: array - title: Features - description: Plan features with current usage. - type: object - required: - - features - title: GetPlanLimitsResponseDto + title: Suggestion + description: Actionable recommendation for query improvement ValidationError: properties: loc: @@ -5148,213 +5209,282 @@ components: - msg - type title: ValidationError - Suggestion: + MonitorStatusEntryDto: properties: - issue: - $ref: '#/components/schemas/IssueType' - message: + id: + type: integer + title: Id + description: Status entry identifier. + status: type: string - title: Message - description: Clear, specific guidance - example: + title: Status + description: Type of lifecycle event. + created_at: + type: string + format: date-time + title: Created At + description: Timestamp of this event. + additional_information: anyOf: - - type: string + - {} - type: 'null' - title: Example - description: Example of improved query + title: Additional Information + description: Event-specific metadata. Null for created, enable, and disable + events. type: object required: - - issue - - message - title: Suggestion - description: Actionable recommendation for query improvement - QueryStatus: - type: string - enum: - - good - - needs_work - - critical - title: QueryStatus - description: Query quality assessment levels - IssueType: - type: string - enum: - - missing_event_type - - too_vague - - too_specific - - wrong_timeframe - - static_content - - article_request - - multiple_event_types - - too_short - - too_long - title: IssueType - description: Specific categories of query issues - WebhookResponseDto: + - id + - status + - created_at + title: MonitorStatusEntry + WebhookStatusItemDto: properties: id: - type: string - format: uuid + type: integer title: Id - description: Webhook identifier. - name: - type: string - title: Name - description: Webhook name. - url: - type: string - title: Url - description: Webhook endpoint URL. - type: - type: string - title: Type - description: Webhook target type. - delivery_mode: + webhook_id: type: string - title: Delivery Mode - description: Delivery mode for webhook payloads. - method: + format: uuid + title: Webhook Id + resource_type: + $ref: '#/components/schemas/WebhookHistoryResourceType' + resource_id: type: string - title: Method - description: HTTP method used for delivery. - headers: - additionalProperties: true - type: object - title: Headers - description: HTTP headers included in requests. - params: - additionalProperties: true - type: object - title: Params - description: Query string parameters. - auth: - anyOf: - - oneOf: - - $ref: '#/components/schemas/BearerAuthResponseDto' - - $ref: '#/components/schemas/ApiKeyAuthResponseDto' - - $ref: '#/components/schemas/BasicAuthResponseDto' - discriminator: - propertyName: type - mapping: - api_key: '#/components/schemas/ApiKeyAuthResponseDto' - basic: '#/components/schemas/BasicAuthResponseDto' - bearer: '#/components/schemas/BearerAuthResponseDto' - - type: 'null' - title: Auth - description: Authentication configuration for this webhook. Sensitive values - (token, API key value, password) are masked as '***'. Present with type - indicator when auth is configured; null when no auth is set. - formatter_config: - anyOf: - - $ref: '#/components/schemas/FormatterConfigDto' - - type: 'null' - description: Formatter configuration. - is_active: - type: boolean - title: Is Active - description: True if the webhook is active; false otherwise. - organization_id: + format: uuid + title: Resource Id + additional_info: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Organization Id - description: Organization that owns this webhook. - created_by_user_id: + title: Additional Info + status_code: anyOf: - - type: string + - type: integer - type: 'null' - title: Created By User Id - description: ID of the user who created this webhook. - created_at: + title: Status Code + attempt_number: + type: integer + title: Attempt Number + timestamp: + type: string + format: date-time + title: Timestamp + delivery_status: + $ref: '#/components/schemas/WebhookDeliveryStatus' + error_message: anyOf: - type: string - type: 'null' - title: Created At - description: Timestamp of when the webhook was created. - updated_at: + title: Error Message + warning_message: anyOf: - type: string - type: 'null' - title: Updated At - description: Timestamp of when the webhook was last updated. + title: Warning Message type: object required: - id - - name - - url - - type - - delivery_mode - - method - - is_active - title: WebhookDto - ResourceItemRequestDto: - properties: - resource_type: - $ref: '#/components/schemas/ProjectResourceTypeEnum' - description: Type of resource to add. - resource_id: - type: string - format: uuid - title: Resource Id - description: ID of the resource to add. - type: object - required: + - webhook_id - resource_type - resource_id - title: ResourceItemDto - SharingInfoDto: + - attempt_number + - timestamp + - delivery_status + title: WebhookStatusItemDto + SourceGroupApiResponseDto: properties: - shared_at: + slug: + type: string + title: Slug + name: + type: string + title: Name + description: anyOf: - type: string - format: date-time - type: 'null' - title: Shared At - shared_by_user_id: + title: Description + type: object + required: + - slug + - name + title: SourceGroupApiResponseDto + ProjectResponseDto: + properties: + project_id: + type: string + format: uuid + title: Project Id + description: Project identifier. + name: + type: string + title: Name + description: Project name. + description: anyOf: - type: string - type: 'null' - title: Shared By User Id - permission: + title: Description + description: Project description. + resources_count: + type: integer + title: Resources Count + description: Number of resources assigned to this project. + default: 0 + created_at: anyOf: - type: string - type: 'null' - title: Permission + title: Created At + description: Project creation timestamp. + updated_at: + anyOf: + - type: string + - type: 'null' + title: Updated At + description: Timestamp of the last update. + sharing_info: + anyOf: + - $ref: '#/components/schemas/SharingInfoDto' + - type: 'null' + description: Present when this project was shared with the authenticated + user. Omitted when the user owns the project. type: object - title: SharingInfo - EntityAssociationType: - type: string - enum: - - mention - - event_associated - title: EntityAssociationType - description: 'How an entity relates to an event: direct actor or merely mentioned.' - ValidatorSchema: + required: + - project_id + - name + title: ProjectResponseDto + ResourceItemResponseDto: + properties: + resource_type: + type: string + title: Resource Type + description: Type of the resource. + resource_id: + type: string + format: uuid + title: Resource Id + description: Resource identifier. + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Resource display name. + created_at: + anyOf: + - type: string + - type: 'null' + title: Created At + description: Resource creation timestamp. + metadata: + additionalProperties: true + type: object + title: Metadata + description: Additional resource-specific metadata. + type: object + required: + - resource_type + - resource_id + title: ProjectResourceDto + WebhookResponseDto: properties: + id: + type: string + format: uuid + title: Id + description: Webhook identifier. name: type: string title: Name - description: Machine-friendly field name (snake_case recommended). - example: is_about_layoffs - description: + description: Webhook name. + url: type: string - title: Description - description: Natural-language criterion evaluated against each article. - Returns true if the article satisfies this criterion. - example: The article is specifically about job layoffs or workforce reductions. + title: Url + description: Webhook endpoint URL. type: type: string - const: boolean title: Type - description: Always 'boolean'. Only articles where all validators return - true count as valid_records. - default: boolean + description: Webhook target type. + delivery_mode: + type: string + title: Delivery Mode + description: Delivery mode for webhook payloads. + method: + type: string + title: Method + description: HTTP method used for delivery. + headers: + additionalProperties: true + type: object + title: Headers + description: HTTP headers included in requests. + params: + additionalProperties: true + type: object + title: Params + description: Query string parameters. + auth: + anyOf: + - oneOf: + - $ref: '#/components/schemas/BearerAuthResponseDto' + - $ref: '#/components/schemas/ApiKeyAuthResponseDto' + - $ref: '#/components/schemas/BasicAuthResponseDto' + discriminator: + propertyName: type + mapping: + api_key: '#/components/schemas/ApiKeyAuthResponseDto' + basic: '#/components/schemas/BasicAuthResponseDto' + bearer: '#/components/schemas/BearerAuthResponseDto' + - type: 'null' + title: Auth + description: Authentication configuration for this webhook. Sensitive values + (token, API key value, password) are masked as '***'. Present with type + indicator when auth is configured; null when no auth is set. + formatter_config: + anyOf: + - $ref: '#/components/schemas/FormatterConfigDto' + - type: 'null' + description: Formatter configuration. + is_active: + type: boolean + title: Is Active + description: True if the webhook is active; false otherwise. + organization_id: + anyOf: + - type: string + - type: 'null' + title: Organization Id + description: Organization that owns this webhook. + created_by_user_id: + anyOf: + - type: string + - type: 'null' + title: Created By User Id + description: ID of the user who created this webhook. + created_at: + anyOf: + - type: string + - type: 'null' + title: Created At + description: Timestamp of when the webhook was created. + updated_at: + anyOf: + - type: string + - type: 'null' + title: Updated At + description: Timestamp of when the webhook was last updated. type: object required: + - id - name - - description - title: ValidatorSchema - description: A boolean classifier applied to every candidate article. + - url + - type + - delivery_mode + - method + - is_active + title: WebhookDto EnrichmentSchema: properties: name: @@ -5379,6 +5509,53 @@ components: - type title: EnrichmentSchema description: A custom extraction field added to each validated article. + ValidatorSchema: + properties: + name: + type: string + title: Name + description: Machine-friendly field name (snake_case recommended). + example: is_about_layoffs + description: + type: string + title: Description + description: Natural-language criterion evaluated against each article. + Returns true if the article satisfies this criterion. + example: The article is specifically about job layoffs or workforce reductions. + type: + type: string + const: boolean + title: Type + description: Always 'boolean'. Only articles where all validators return + true count as valid_records. + default: boolean + type: object + required: + - name + - description + title: ValidatorSchema + description: A boolean classifier applied to every candidate article. + ApiKeyAuthDto: + properties: + type: + type: string + const: api_key + title: Type + description: Authentication type. + header: + type: string + title: Header + description: HTTP header name for the API key, e.g. 'X-API-Key'. + value: + type: string + title: Value + description: API key value. + type: object + required: + - type + - header + - value + title: ApiKeyAuth HttpMethod: type: string enum: @@ -5389,36 +5566,15 @@ components: - DELETE title: HttpMethod description: HTTP method used for webhook delivery. - BasicAuthDto: + FormatterConfigDto: properties: - type: - type: string - const: basic - title: Type - description: Authentication type. - username: + template: type: string - title: Username - description: Basic auth username. - password: - type: string - title: Password - description: Basic auth password. - type: object - required: - - type - - username - - password - title: BasicAuth - FormatterConfigDto: - properties: - template: - type: string - title: Template - description: Liquid template string rendered at dispatch time. Maximum 10 - KB. - example: '{"event": "{{ event }}", "count": {{ records_count }}}' - content_type: + title: Template + description: Liquid template string rendered at dispatch time. Maximum 10 + KB. + example: '{"event": "{{ event }}", "count": {{ records_count }}}' + content_type: type: string title: Content Type description: 'Content-Type of the rendered output. Supported values: application/json, @@ -5438,27 +5594,37 @@ components: title: DeliveryMode description: Delivery mode for webhook payloads. 'full' delivers the entire result set in one call; 'per_record' sends one call per article. - ApiKeyAuthDto: + BasicAuthDto: properties: type: type: string - const: api_key + const: basic title: Type description: Authentication type. - header: + username: type: string - title: Header - description: HTTP header name for the API key, e.g. 'X-API-Key'. - value: + title: Username + description: Basic auth username. + password: type: string - title: Value - description: API key value. + title: Password + description: Basic auth password. type: object required: - type - - header - - value - title: ApiKeyAuth + - username + - password + title: BasicAuth + WebhookType: + type: string + enum: + - generic + - slack + - teams + - custom + title: WebhookType + description: Webhook target type. 'slack' and 'teams' send pre-formatted payloads; + 'generic' and 'custom' send the raw result payload. BearerAuthDto: properties: type: @@ -5475,136 +5641,117 @@ components: - type - token title: BearerAuth - WebhookType: + AdditionalAttributesDto: + properties: + company_attributes: + anyOf: + - $ref: '#/components/schemas/CompanyAttributesDto' + - type: 'null' + description: Identifying attributes for a company entity. + additionalProperties: true + type: object + title: AdditionalAttributes + EntityAssociationType: type: string enum: - - generic - - slack - - teams - - custom - title: WebhookType - description: Webhook target type. 'slack' and 'teams' send pre-formatted payloads; - 'generic' and 'custom' send the raw result payload. - WebhookResourceMappingResponseDto: + - mention + - event_associated + title: EntityAssociationType + description: 'How an entity relates to an event: direct actor or merely mentioned.' + MonitorJobItemResponseDto: properties: - id: - type: string - format: uuid - title: Id - description: Mapping identifier. - webhook_id: - type: string - format: uuid - title: Webhook Id - description: Webhook identifier. - resource_type: - type: string - title: Resource Type - description: Type of the assigned resource. - resource_id: + job_id: type: string format: uuid - title: Resource Id - description: Resource identifier. - assigned_at: + title: Job Id + description: Unique identifier for this job execution. + start_date: anyOf: - type: string - type: 'null' - title: Assigned At - description: Timestamp of when the resource was assigned. + title: Start Date + description: Start of the data collection time window for this job execution. + end_date: + anyOf: + - type: string + - type: 'null' + title: End Date + description: End of the data collection time window for this job execution. type: object required: - - id - - webhook_id - - resource_type - - resource_id - title: WebhookResourceMappingDto - WebhookStatusItemDto: + - job_id + title: MonitorJobItem + CsvValidationReportDto: properties: - id: + total_rows: type: integer - title: Id - webhook_id: + title: Total Rows + description: Total number of data rows in the uploaded CSV excluding the + header. + valid_rows: + type: integer + title: Valid Rows + description: Number of rows successfully processed into entities. + skipped_count: + type: integer + title: Skipped Count + description: Number of rows skipped due to validation errors. + skipped_rows: + items: + $ref: '#/components/schemas/CsvSkippedRowDto' + type: array + title: Skipped Rows + description: Details for each skipped row. + type: object + required: + - total_rows + - valid_rows + - skipped_count + - skipped_rows + title: ValidationReport + EntitySummaryDto: + properties: + id: type: string format: uuid - title: Webhook Id - resource_type: - $ref: '#/components/schemas/WebhookHistoryResourceType' - resource_id: + title: Id + description: Unique identifier of the entity. + name: type: string - format: uuid - title: Resource Id - additional_info: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Additional Info - status_code: - anyOf: - - type: integer - - type: 'null' - title: Status Code - attempt_number: - type: integer - title: Attempt Number - timestamp: + title: Name + description: Entity name. + entity_type: type: string - format: date-time - title: Timestamp - delivery_status: - $ref: '#/components/schemas/WebhookDeliveryStatus' - error_message: + title: Entity Type + description: The type of entity. + status: + type: string + title: Status + description: Processing status of the entity. + description: anyOf: - type: string - type: 'null' - title: Error Message - warning_message: + title: Description + description: Free-text description. + external_entity_id: anyOf: - type: string - type: 'null' - title: Warning Message + title: External Entity Id + description: External identifier for this entity. Null when not set. + attributes: + anyOf: + - $ref: '#/components/schemas/AdditionalAttributesDto' + - type: 'null' + description: Type-specific attributes. type: object required: - id - - webhook_id - - resource_type - - resource_id - - attempt_number - - timestamp - - delivery_status - title: WebhookStatusItemDto - ResourceResultResponseDto: - properties: - resource_type: - type: string - title: Resource Type - description: Type of the resource. - resource_id: - type: string - format: uuid - title: Resource Id - description: Resource identifier. - success: - type: boolean - title: Success - description: True if this resource was processed successfully. - message: - type: string - title: Message - description: Per-resource result message. - already_exists: - type: boolean - title: Already Exists - description: True if the resource is already assigned to this project. - default: false - type: object - required: - - resource_type - - resource_id - - success - - message - title: ResourceResultDto + - name + - entity_type + - status + title: EntitySummary ConnectedDatasetDto: properties: id: @@ -5625,43 +5772,179 @@ components: type: object required: - id - - name - title: ConnectedDataset - SourceGroupRefDto: + - name + title: ConnectedDataset + RunInfoDto: + properties: + first_run: + anyOf: + - type: string + - type: 'null' + title: First Run + description: ISO 8601 timestamp of the first completed run. + last_run: + anyOf: + - type: string + - type: 'null' + title: Last Run + description: ISO 8601 timestamp of the most recent completed run. + type: object + title: RunInfo + SharingInfoDto: + properties: + shared_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Shared At + shared_by_user_id: + anyOf: + - type: string + - type: 'null' + title: Shared By User Id + permission: + anyOf: + - type: string + - type: 'null' + title: Permission + type: object + title: SharingInfo + MonitorRecordDto: + properties: + record_id: + anyOf: + - type: string + - type: 'null' + title: Record Id + description: Unique cluster identifier for this record. + record_title: + anyOf: + - type: string + - type: 'null' + title: Record Title + description: Event or cluster title. + enrichment: + additionalProperties: true + type: object + title: Enrichment + description: Custom enrichment fields extracted for this record. Keys match + the enrichment names defined in the job. Values are job-specific. For + 'company' type enrichments, each value is a CompanyEnrichmentOutput object. + enrichment_confidence: + anyOf: + - additionalProperties: + type: number + type: object + - type: 'null' + title: Enrichment Confidence + description: Per-field confidence scores for enrichment values. Keys mirror + the enrichment dict; values are floats in [0, 1]. + citations: + anyOf: + - items: + $ref: '#/components/schemas/MonitorCitationDto' + type: array + - type: 'null' + title: Citations + description: Source articles included in this record, with job attribution. + connected_entities: + anyOf: + - items: + $ref: '#/components/schemas/ConnectedEntityDto' + type: array + - type: 'null' + title: Connected Entities + description: Entities from connected datasets that matched this record. + added_on: + anyOf: + - type: string + - type: 'null' + title: Added On + description: ISO 8601 timestamp when this record was first added. + updated_on: + anyOf: + - type: string + - type: 'null' + title: Updated On + description: ISO 8601 timestamp when this record was last updated. + type: object + title: MonitorRecord + ReferenceJob: + properties: + query: + anyOf: + - type: string + - type: 'null' + title: Query + description: Plain text query from the reference job. + context: + anyOf: + - type: string + - type: 'null' + title: Context + description: Context provided with the reference job query. + source_groups: + anyOf: + - items: + $ref: '#/components/schemas/SourceGroupRefDto' + type: array + - type: 'null' + title: Source Groups + description: Source groups attached to the reference job, each with slug, + name, and description. + type: object + title: ReferenceJob + WebhookResourceMappingResponseDto: + properties: + id: + type: string + format: uuid + title: Id + description: Mapping identifier. + webhook_id: + type: string + format: uuid + title: Webhook Id + description: Webhook identifier. + resource_type: + type: string + title: Resource Type + description: Type of the assigned resource. + resource_id: + type: string + format: uuid + title: Resource Id + description: Resource identifier. + assigned_at: + anyOf: + - type: string + - type: 'null' + title: Assigned At + description: Timestamp of when the resource was assigned. + type: object + required: + - id + - webhook_id + - resource_type + - resource_id + title: WebhookResourceMappingDto + DateRangeDto: properties: - slug: - type: string - title: Slug - description: Source group slug. - name: - type: string - title: Name - description: Source group name. - description: + start_date: anyOf: - type: string - type: 'null' - title: Description - description: Source group description. + title: Start Date + description: Inclusive start of the article date range (ISO 8601). + end_date: + anyOf: + - type: string + - type: 'null' + title: End Date + description: Inclusive end of the article date range (ISO 8601). type: object - required: - - slug - - name - title: SourceGroupRef - PublicJobStatus: - type: string - enum: - - submitted - - analyzing - - fetching - - clustering - - enriching - - completed - - failed - title: PublicJobStatus - description: 'Current job processing status. Jobs progress through stages: submitted - → analyzing → fetching → clustering → enriching → completed. Poll /catchAll/status/{job_id} - every 30-60 seconds until completed (typically 10-15 minutes).' + title: DateRange ArticleRecordDto: properties: record_id: @@ -5718,156 +6001,41 @@ components: the classifier could not tag. type: object title: Record - DateRangeDto: - properties: - start_date: - anyOf: - - type: string - - type: 'null' - title: Start Date - description: Inclusive start of the article date range (ISO 8601). - end_date: - anyOf: - - type: string - - type: 'null' - title: End Date - description: Inclusive end of the article date range (ISO 8601). - type: object - title: DateRange - MonitorJobItemResponseDto: - properties: - job_id: - type: string - format: uuid - title: Job Id - description: Unique identifier for this job execution. - start_date: - anyOf: - - type: string - - type: 'null' - title: Start Date - description: Start of the data collection time window for this job execution. - end_date: - anyOf: - - type: string - - type: 'null' - title: End Date - description: End of the data collection time window for this job execution. - type: object - required: - - job_id - title: MonitorJobItem - DatasetStatusEntryDto: - properties: - status: - type: string - title: Status - description: Dataset processing status. - additional_information: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Additional Information - description: Additional context about the status change. - created_at: - anyOf: - - type: string - format: date-time - - type: 'null' - title: Created At - description: Timestamp of when this status was set. - type: object - required: - - status - title: DatasetStatusEntry - AdditionalAttributesDto: - properties: - company_attributes: - anyOf: - - $ref: '#/components/schemas/CompanyAttributesDto' - - type: 'null' - description: Identifying attributes for a company entity. - additionalProperties: true - type: object - title: AdditionalAttributes - JobStep: - properties: - status: - $ref: '#/components/schemas/PublicJobStatus' - order: - type: integer - title: Order - completed: - type: boolean - title: Completed - default: false - type: object - required: - - status - - order - title: JobStep - MonitorStatusEntryDto: - properties: - id: - type: integer - title: Id - description: Status entry identifier. - status: - type: string - title: Status - description: Type of lifecycle event. - created_at: - type: string - format: date-time - title: Created At - description: Timestamp of this event. - additional_information: - anyOf: - - {} - - type: 'null' - title: Additional Information - description: Event-specific metadata. Null for created, enable, and disable - events. - type: object - required: - - id - - status - - created_at - title: MonitorStatusEntry - ResourceItemResponseDto: + PublicJobStatus: + type: string + enum: + - submitted + - analyzing + - fetching + - clustering + - enriching + - completed + - failed + title: PublicJobStatus + description: 'Current job processing status. Jobs progress through stages: submitted + → analyzing → fetching → clustering → enriching → completed. Poll /catchAll/status/{job_id} + every 30-60 seconds until completed (typically 10-15 minutes).' + SourceGroupRefDto: properties: - resource_type: - type: string - title: Resource Type - description: Type of the resource. - resource_id: + slug: type: string - format: uuid - title: Resource Id - description: Resource identifier. + title: Slug + description: Source group slug. name: - anyOf: - - type: string - - type: 'null' + type: string title: Name - description: Resource display name. - created_at: + description: Source group name. + description: anyOf: - type: string - type: 'null' - title: Created At - description: Resource creation timestamp. - metadata: - additionalProperties: true - type: object - title: Metadata - description: Additional resource-specific metadata. + title: Description + description: Source group description. type: object required: - - resource_type - - resource_id - title: ProjectResourceDto + - slug + - name + title: SourceGroupRef UserJobResponseDto: properties: job_id: @@ -5908,120 +6076,90 @@ components: - created_at - status - user_key - title: UserJob - ReferenceJob: - properties: - query: - anyOf: - - type: string - - type: 'null' - title: Query - description: Plain text query from the reference job. - context: - anyOf: - - type: string - - type: 'null' - title: Context - description: Context provided with the reference job query. - source_groups: - anyOf: - - items: - $ref: '#/components/schemas/SourceGroupRefDto' - type: array - - type: 'null' - title: Source Groups - description: Source groups attached to the reference job, each with slug, - name, and description. - type: object - title: ReferenceJob - RunInfoDto: + title: UserJob + JobStep: properties: - first_run: - anyOf: - - type: string - - type: 'null' - title: First Run - description: ISO 8601 timestamp of the first completed run. - last_run: - anyOf: - - type: string - - type: 'null' - title: Last Run - description: ISO 8601 timestamp of the most recent completed run. + status: + $ref: '#/components/schemas/PublicJobStatus' + order: + type: integer + title: Order + completed: + type: boolean + title: Completed + default: false type: object - title: RunInfo - MonitorRecordDto: + required: + - status + - order + title: JobStep + DatasetStatusEntryDto: properties: - record_id: - anyOf: - - type: string - - type: 'null' - title: Record Id - description: Unique cluster identifier for this record. - record_title: - anyOf: - - type: string - - type: 'null' - title: Record Title - description: Event or cluster title. - enrichment: - additionalProperties: true - type: object - title: Enrichment - description: Custom enrichment fields extracted for this record. Keys match - the enrichment names defined in the job. Values are job-specific. For - 'company' type enrichments, each value is a CompanyEnrichmentOutput object. - enrichment_confidence: + status: + type: string + title: Status + description: Dataset processing status. + additional_information: anyOf: - - additionalProperties: - type: number + - additionalProperties: true type: object - type: 'null' - title: Enrichment Confidence - description: Per-field confidence scores for enrichment values. Keys mirror - the enrichment dict; values are floats in [0, 1]. - citations: - anyOf: - - items: - $ref: '#/components/schemas/MonitorCitationDto' - type: array - - type: 'null' - title: Citations - description: Source articles included in this record, with job attribution. - connected_entities: - anyOf: - - items: - $ref: '#/components/schemas/ConnectedEntityDto' - type: array - - type: 'null' - title: Connected Entities - description: Entities from connected datasets that matched this record. - added_on: - anyOf: - - type: string - - type: 'null' - title: Added On - description: ISO 8601 timestamp when this record was first added. - updated_on: + title: Additional Information + description: Additional context about the status change. + created_at: anyOf: - type: string + format: date-time - type: 'null' - title: Updated On - description: ISO 8601 timestamp when this record was last updated. + title: Created At + description: Timestamp of when this status was set. type: object - title: MonitorRecord + required: + - status + title: DatasetStatusEntry + ResourceResultResponseDto: + properties: + resource_type: + type: string + title: Resource Type + description: Type of the resource. + resource_id: + type: string + format: uuid + title: Resource Id + description: Resource identifier. + success: + type: boolean + title: Success + description: True if this resource was processed successfully. + message: + type: string + title: Message + description: Per-resource result message. + already_exists: + type: boolean + title: Already Exists + description: True if the resource is already assigned to this project. + default: false + type: object + required: + - resource_type + - resource_id + - success + - message + title: ResourceResultDto MonitorListItemResponseDto: properties: monitor_id: type: string format: uuid title: Monitor Id - description: Event monitor identifier. + description: Monitor identifier. reference_job_id: type: string format: uuid title: Reference Job Id - description: Job identifier used as a reference for this event monitor. + description: Job identifier used as a reference for this monitor. reference_job_query: type: string title: Reference Job Query @@ -6030,18 +6168,18 @@ components: anyOf: - $ref: '#/components/schemas/SharingInfoDto' - type: 'null' - description: Present when this event monitor was shared with the authenticated - user. Omitted when the user owns the event monitor. + description: Present when this monitor was shared with the authenticated + user. Omitted when the user owns the monitor. enabled: type: boolean title: Enabled - description: True if the event monitor is currently active; false otherwise. + description: True if the monitor is currently active; false otherwise. schedule: anyOf: - type: string - type: 'null' title: Schedule - description: Cron expression for event monitor schedule. + description: Cron expression for monitor schedule. timezone: anyOf: - type: string @@ -6053,160 +6191,41 @@ components: - type: string - type: 'null' title: Created At - description: Timestamp of when the event monitor was created. + description: Timestamp of when the monitor was created. schedule_human_readable: anyOf: - type: string - type: 'null' title: Schedule Human Readable - description: Event monitor schedule in plain text format. + description: Monitor schedule in plain text format. user_key: anyOf: - type: string - type: 'null' title: User Key - description: Masked API key associated with this event monitor. + description: Masked API key associated with this monitor. type: object required: - monitor_id - reference_job_id - reference_job_query - - enabled - title: MonitorListItemDto - SourceGroupApiResponseDto: - properties: - slug: - type: string - title: Slug - name: - type: string - title: Name - description: - anyOf: - - type: string - - type: 'null' - title: Description - type: object - required: - - slug - - name - title: SourceGroupApiResponseDto - ProjectResponseDto: - properties: - project_id: - type: string - format: uuid - title: Project Id - description: Project identifier. - name: - type: string - title: Name - description: Project name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Project description. - resources_count: - type: integer - title: Resources Count - description: Number of resources assigned to this project. - default: 0 - created_at: - anyOf: - - type: string - - type: 'null' - title: Created At - description: Project creation timestamp. - updated_at: - anyOf: - - type: string - - type: 'null' - title: Updated At - description: Timestamp of the last update. - sharing_info: - anyOf: - - $ref: '#/components/schemas/SharingInfoDto' - - type: 'null' - description: Present when this project was shared with the authenticated - user. Omitted when the user owns the project. - type: object - required: - - project_id - - name - title: ProjectResponseDto - CsvValidationReportDto: - properties: - total_rows: - type: integer - title: Total Rows - description: Total number of data rows in the uploaded CSV excluding the - header. - valid_rows: - type: integer - title: Valid Rows - description: Number of rows successfully processed into entities. - skipped_count: - type: integer - title: Skipped Count - description: Number of rows skipped due to validation errors. - skipped_rows: - items: - $ref: '#/components/schemas/CsvSkippedRowDto' - type: array - title: Skipped Rows - description: Details for each skipped row. - type: object - required: - - total_rows - - valid_rows - - skipped_count - - skipped_rows - title: ValidationReport - EntitySummaryDto: - properties: - id: - type: string - format: uuid - title: Id - description: Unique identifier of the entity. - name: - type: string - title: Name - description: Entity name. - entity_type: - type: string - title: Entity Type - description: The type of entity. - status: - type: string - title: Status - description: Processing status of the entity. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Free-text description. - external_entity_id: - anyOf: - - type: string - - type: 'null' - title: External Entity Id - description: External identifier for this entity. Null when not set. - attributes: - anyOf: - - $ref: '#/components/schemas/AdditionalAttributesDto' - - type: 'null' - description: Type-specific attributes. + - enabled + title: MonitorListItemDto + ResourceItemRequestDto: + properties: + resource_type: + $ref: '#/components/schemas/ProjectResourceTypeEnum' + description: Type of resource to add. + resource_id: + type: string + format: uuid + title: Resource Id + description: ID of the resource to add. type: object required: - - id - - name - - entity_type - - status - title: EntitySummary + - resource_type + - resource_id + title: ResourceItemDto BillingFeatureWithUsage: properties: name: @@ -6241,6 +6260,35 @@ components: - name - code title: PlanFeature + WebhookDeliveryStatus: + type: string + enum: + - SUCCESS + - FAILED + title: WebhookDeliveryStatus + description: Webhook delivery outcome status. + WebhookHistoryResourceType: + type: string + enum: + - job + - monitor + - monitor_group + - test + title: WebhookHistoryResourceType + description: 'Resource types a webhook_status row can be recorded against. + + + A superset of MappableResourceType: real deliveries are always tied to an + + attachable resource (job/monitor/monitor_group), but a manual test delivery + + (POST /webhooks/{id}/test) isn''t tied to any real resource, so it is recorded + + against the synthetic `test` type instead. Kept separate from + + MappableResourceType so `test` can never be accepted where an attachable + + resource type is expected (e.g. assigning a webhook to a resource).' BasicAuthResponseDto: properties: type: @@ -6313,35 +6361,96 @@ components: title: EnrichmentType description: 'Canonical enrichment types: text, number, date, option, url, company. See Company enrichment docs for the company type data model.' - WebhookDeliveryStatus: - type: string - enum: - - SUCCESS - - FAILED - title: WebhookDeliveryStatus - description: Webhook delivery outcome status. - WebhookHistoryResourceType: - type: string - enum: - - job - - monitor - - monitor_group - - test - title: WebhookHistoryResourceType - description: 'Resource types a webhook_status row can be recorded against. - - - A superset of MappableResourceType: real deliveries are always tied to an - - attachable resource (job/event monitor/event monitor group), but a manual test delivery - - (POST /webhooks/{id}/test) isn''t tied to any real resource, so it is recorded - - against the synthetic `test` type instead. Kept separate from - - MappableResourceType so `test` can never be accepted where an attachable - - resource type is expected (e.g. assigning a webhook to a resource).' + CompanyAttributesDto: + properties: + alternative_names: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Alternative Names + description: Alternative names, abbreviations, or aliases for the company. + domain: + anyOf: + - type: string + - type: 'null' + title: Domain + description: Company website domain without protocol or trailing slash. + On create, the entity must have this or description set. + key_persons: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Key Persons + description: Names of key people associated with the company. + type: object + title: CompanyAttributes + CsvSkippedRowDto: + properties: + row: + type: integer + title: Row + description: 1-based row number in the CSV file including the header row. + reason: + type: string + title: Reason + description: Human-readable explanation of why the row was skipped. + type: object + required: + - row + - reason + title: SkippedRow + MonitorCitationDto: + properties: + type: + anyOf: + - type: string + - type: 'null' + title: Type + description: Source type of the citation, e.g. 'news'. + title: + anyOf: + - type: string + - type: 'null' + title: Title + description: Title of the source document. + link: + anyOf: + - type: string + - type: 'null' + format: uri + title: Link + description: URL to the source document. + published_date: + anyOf: + - type: string + - type: 'null' + title: Published Date + description: Publication date of the source document. + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: Citation identifier. + job_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Job Id + description: Job identifier that found this citation. + added_on: + anyOf: + - type: string + - type: 'null' + title: Added On + description: ISO 8601 timestamp when this citation was added. + type: object + title: MonitorCitation ConnectedEntityDto: properties: entity_id: @@ -6440,96 +6549,6 @@ components: description: Publication date of the source document. type: object title: Citation - CompanyAttributesDto: - properties: - alternative_names: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Alternative Names - description: Alternative names, abbreviations, or aliases for the company. - domain: - anyOf: - - type: string - - type: 'null' - title: Domain - description: Company website domain without protocol or trailing slash. - On create, the entity must have this or description set. - key_persons: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Key Persons - description: Names of key people associated with the company. - type: object - title: CompanyAttributes - MonitorCitationDto: - properties: - type: - anyOf: - - type: string - - type: 'null' - title: Type - description: Source type of the citation, e.g. 'news'. - title: - anyOf: - - type: string - - type: 'null' - title: Title - description: Title of the source document. - link: - anyOf: - - type: string - - type: 'null' - format: uri - title: Link - description: URL to the source document. - published_date: - anyOf: - - type: string - - type: 'null' - title: Published Date - description: Publication date of the source document. - id: - anyOf: - - type: string - - type: 'null' - title: Id - description: Citation identifier. - job_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Job Id - description: Job identifier that found this citation. - added_on: - anyOf: - - type: string - - type: 'null' - title: Added On - description: ISO 8601 timestamp when this citation was added. - type: object - title: MonitorCitation - CsvSkippedRowDto: - properties: - row: - type: integer - title: Row - description: 1-based row number in the CSV file including the header row. - reason: - type: string - title: Reason - description: Human-readable explanation of why the row was skipped. - type: object - required: - - row - - reason - title: SkippedRow securitySchemes: ApiKeyAuth: type: apiKey diff --git a/web-search-api/concepts/event-monitors.mdx b/web-search-api/concepts/event-monitors.mdx index 28c8e34..a0ea431 100644 --- a/web-search-api/concepts/event-monitors.mdx +++ b/web-search-api/concepts/event-monitors.mdx @@ -458,14 +458,14 @@ Files.write(Paths.get("monitor-results.csv"), csvData); ## Manage event monitors -Use these endpoints to update webhook assignments, pause, resume, or delete an -event monitor, and inspect its execution history. +Use these endpoints to update webhook assignments, record limit, or schedule; +pause, resume, or delete an event monitor; and inspect its execution history. ### Update event monitor -Update webhook assignments or the record limit for an existing event monitor. Pass a -new list of webhook IDs to replace existing assignments. Pass an empty array to -clear all assignments: +Update webhook assignments, the record limit, or the schedule for an existing event +monitor. Omitted fields are left unchanged. Pass a new list of webhook IDs to +replace existing assignments. Pass an empty array to clear all assignments: ```bash cURL @@ -527,9 +527,75 @@ Response: } ``` +#### Change the schedule + +Pass `schedule` to replace the event monitor's current schedule without +recreating it. The event monitor keeps its ID, reference job, webhooks, and +execution history: + + +```bash cURL +curl -X PATCH "https://catchall.newscatcherapi.com/catchAll/monitors/{monitor_id}" \ + -H "x-api-key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "schedule": "every Monday at 9 AM EST" + }' +``` +```json JSON +{ + "schedule": "every Monday at 9 AM EST" +} +``` +```python Python +from newscatcher_catchall import CatchAllApi + +client = CatchAllApi(api_key="YOUR_API_KEY") + +client.monitors.update_monitor( + monitor_id="3fec5b07-8786-46d7-9486-d43ff67eccd4", + schedule="every Monday at 9 AM EST", +) +``` +```typescript TypeScript +import { CatchAllApiClient } from "newscatcher-catchall-sdk"; + +const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" }); + +await client.monitors.updateMonitor({ + monitor_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4", + schedule: "every Monday at 9 AM EST", +}); +``` +```java Java +import com.newscatcher.catchall.CatchAllApi; +import com.newscatcher.catchall.resources.monitors.requests.UpdateMonitorRequestDto; + +CatchAllApi client = CatchAllApi.builder() + .apiKey("YOUR_API_KEY") + .build(); + +client.monitors().updateMonitor( + "3fec5b07-8786-46d7-9486-d43ff67eccd4", + UpdateMonitorRequestDto.builder() + .schedule("every Monday at 9 AM EST") + .build() +); +``` + + +- `schedule` uses the same natural-language format as event monitor creation. +- `timezone` (optional, default `UTC`) sets an IANA timezone for the new + schedule, such as `America/New_York`. A timezone in the `schedule` text takes + precedence. `timezone` is ignored if `schedule` is not set. +- The new schedule takes effect from the next scheduler reload, and the old + schedule stops firing. +- The API returns `422` if the schedule can't be parsed or runs would be spaced + too closely. + - Schedule and reference job cannot be modified. To change the query or schedule, - create a new event monitor. + The reference job cannot be modified. To change the query, validators, or + enrichments, create a new event monitor from a different reference job. ### Enable event monitor diff --git a/web-search-api/get-started/changelog.mdx b/web-search-api/get-started/changelog.mdx index a13f09c..5acad01 100644 --- a/web-search-api/get-started/changelog.mdx +++ b/web-search-api/get-started/changelog.mdx @@ -5,6 +5,38 @@ description: Track updates, improvements, and fixes to the CatchAll API. rss: true --- + +## Update event monitor schedules + +You can now change when an existing event monitor runs without deleting and +recreating it. This release also makes Raw Query fetching more reliable. + +### Change an event monitor's schedule + +[`PATCH /catchAll/monitors/{monitor_id}`](/web-search-api/api-reference/event-monitors/update-monitor) +accepts two new optional fields: + +- `schedule` (string): A new natural-language schedule, such as + `every Monday at 9 AM EST`, that replaces the current one. Omit to keep the + current schedule. +- `timezone` (string, default `UTC`): IANA timezone for the new schedule. A + timezone in the `schedule` text takes precedence. Ignored if `schedule` is not + set. + +The event monitor keeps its ID, reference job, webhooks, and execution history. +The new schedule takes effect from the next scheduler reload, and the old one +stops firing. The endpoint returns `422` if the schedule can't be parsed or runs +would be spaced too closely. See +[Event Monitors](/web-search-api/concepts/event-monitors#change-the-schedule). + +### Fixes and improvements + +- Fixed Raw Query fetches that could fail partway through a large result set. + Transient fetch failures now retry with exponential backoff and recover + consistently. +- Validator evaluation runs on a faster, lower-cost model. + + ## Sharper watchlist search and stricter validators diff --git a/web-search-api/how-to/configure-event-monitors.mdx b/web-search-api/how-to/configure-event-monitors.mdx index c1c18d3..ea81101 100644 --- a/web-search-api/how-to/configure-event-monitors.mdx +++ b/web-search-api/how-to/configure-event-monitors.mdx @@ -415,8 +415,8 @@ Log all webhook events for debugging: ## Update event monitor configuration -Update webhook assignments or the record limit for an existing event monitor without -recreating it. +Update webhook assignments, the record limit, or the schedule for an existing event +monitor without recreating it. ### When to update @@ -424,10 +424,11 @@ Update an event monitor when you need to: - Change which webhooks receive notifications - Clear all webhook assignments - Adjust the maximum records per run +- Change how often or at what time the event monitor runs - Schedule and reference job cannot be modified. To change the query or schedule, - create a new event monitor. + The reference job cannot be modified. To change the query, create a new event + monitor. ### Update procedure @@ -500,6 +501,13 @@ System.out.println("Updated: " + response.getMonitorId().orElse("N/A")); To clear all webhook assignments, pass an empty array: `"webhook_ids": []`. +To change the schedule, pass `schedule` (and optionally `timezone`) in the same +request body, for example `{"schedule": "every Monday at 9 AM EST"}`. The new +schedule takes effect from the next scheduler reload, and the old schedule stops +firing. The API returns `422` if the schedule can't be parsed or runs would be +spaced too closely. See [Choose appropriate schedules](#choose-appropriate-schedules) +for supported formats. + @@ -513,8 +521,8 @@ To clear all webhook assignments, pass an empty array: `"webhook_ids": []`. - Updates take effect immediately. The next scheduled execution uses the new - configuration. + Webhook and limit updates take effect immediately. The next scheduled execution + uses the new configuration. Schedule changes apply from the next scheduler reload. ## See also