From b381b0d0520a677faad402e3f4615cefd32f8d98 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 23 Oct 2026 08:41:25 +0000 Subject: [PATCH 1/2] chore: sync FastAPI OAS snapshot 2026-10-23 --- .../api-reference/fastapi-openapi.yml | 5156 ++++++++--------- 1 file changed, 2578 insertions(+), 2578 deletions(-) diff --git a/web-search-api/api-reference/fastapi-openapi.yml b/web-search-api/api-reference/fastapi-openapi.yml index 9c4f2f5..6f58d46 100644 --- a/web-search-api/api-reference/fastapi-openapi.yml +++ b/web-search-api/api-reference/fastapi-openapi.yml @@ -2706,6 +2706,24 @@ tags: description: Operations to check API health and version. components: schemas: + HTTPValidationError: + properties: + detail: + items: + $ref: '#/components/schemas/ValidationError' + type: array + title: Detail + type: object + title: HTTPValidationError + CheckQueryQualityRequestDto: + properties: + query: + type: string + title: Query + type: object + required: + - query + title: CheckQueryQualityRequestDto CheckQueryQualityResponseDto: properties: status: @@ -2747,698 +2765,905 @@ components: - confidence title: CheckQueryQualityResponseDto description: Complete query validation result - HTTPValidationError: - properties: - detail: - items: - $ref: '#/components/schemas/ValidationError' - type: array - title: Detail - type: object - title: HTTPValidationError - CheckQueryQualityRequestDto: - properties: - query: - type: string - title: Query - type: object - required: - - query - title: CheckQueryQualityRequestDto - ContinueResponseDto: + ContinueRequestDto: properties: job_id: type: string format: uuid title: Job Id - description: UUID of the continued job. - previous_limit: + description: Existing job to extend with a higher result limit. + new_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 + description: New limit, must be greater than the current limit. If null, + raises to the plan maximum. + example: 250 type: object required: - job_id - - new_limit - title: ContinueResponseDto - TestWebhookRequestDto: + title: ContinueRequestDto + example: + job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + new_limit: 250 + SortOrder: + type: string + enum: + - asc + - desc + title: SortOrder + description: Sort direction for list results. 'asc' for ascending (oldest first), + 'desc' for descending (newest first). + 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.' + TestWebhookResponseDto: properties: - payload: + 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: - - additionalProperties: true - type: object + - type: integer - type: 'null' - title: Payload - description: Custom payload to send in the test request. + 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 - title: TestWebhookRequestDto - CsvUploadToExistingResponseDto: + required: + - success + - message + title: TestWebhookResponseDto + Body_createDatasetFromCsv: + properties: + file: + type: string + format: binary + title: File + name: + type: string + title: Name + description: + type: string + title: Description + project_id: + type: string + title: Project Id + type: object + required: + - file + - name + title: Body_createDatasetFromCsv + CsvUploadCreateResponseDto: properties: dataset_id: type: string format: uuid title: Dataset Id - description: ID of the dataset that was updated. + 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 new entities created from the CSV. + 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: UploadCsvToDatasetResponse - CreateProjectResponseDto: + title: CreateDatasetCsvResponse + CreateWebhookRequestDto: properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: + name: type: string - title: Message - description: Human-readable result message. + title: Name + description: Human-readable label for this webhook. + example: Layoffs Alert + url: + type: string + title: Url + description: Destination URL that receives the payload. + example: https://hooks.slack.com/services/T000/B000/xxxx + type: + $ref: '#/components/schemas/WebhookType' + default: generic + delivery_mode: + $ref: '#/components/schemas/DeliveryMode' + description: '''full'' delivers the entire result set in one call; ''per_record'' + sends one call per article.' + default: full + method: + $ref: '#/components/schemas/HttpMethod' + description: HTTP method used for delivery. + default: POST + headers: + additionalProperties: + type: string + type: object + title: Headers + description: Custom HTTP headers forwarded with each delivery. + default: {} + params: + additionalProperties: + type: string + type: object + title: Params + description: Query parameters appended to the webhook URL. + default: {} + 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: Custom payload formatter. Required when type is 'custom'. 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. + description: Optional project ID to associate this webhook with immediately + upon creation. type: object required: - - success - - message - title: CreateProjectResponseDto - 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.' - AddResourceResponseDto: + - name + - url + title: CreateWebhookRequestDto + example: + delivery_mode: full + name: Layoffs Alert + type: slack + url: https://hooks.slack.com/services/T000/B000/xxxx + ListMonitorsResponseDto: 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 - EntityType: - type: string - enum: - - company - - person - title: EntityType - description: The type of entity. 'company' for organizations (default), 'person' - for individuals. - GetProjectResponseDto: + total: + type: integer + title: Total + description: Total number of monitors for this user. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of monitors per page. + total_pages: + type: integer + title: Total Pages + description: Total number of pages available. + monitors: + items: + $ref: '#/components/schemas/MonitorListItemResponseDto' + type: array + title: Monitors + description: Array of monitor summaries. + type: object + required: + - total + - page + - page_size + - total_pages + - monitors + title: ListMonitorsResponseDto + SuggestInitializeResponseDto: + 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: + items: + $ref: '#/components/schemas/EnrichmentSchema' + 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. + type: object + required: + - query + title: InitializeResponseDto + AssignWebhookResourceResponseDto: properties: success: type: boolean title: Success description: True if the operation succeeded; false otherwise. message: - type: string + anyOf: + - type: string + - type: 'null' title: Message description: Human-readable result message. - project_id: + already_existed: + type: boolean + title: Already Existed + description: True if the mapping already existed. + default: false + mapping: anyOf: - - type: string - format: uuid + - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' - type: 'null' - title: Project Id - description: Project identifier. + description: Created or existing resource mapping. + type: object + required: + - success + title: AssignWebhookResourceResponseDto + UpdateProjectRequestDto: + properties: name: anyOf: - type: string - type: 'null' title: Name - description: Project name. + description: New name for the project. 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: + description: New description for the project. + type: object + title: UpdateProjectRequestDto + AddResourceRequestDto: + properties: + resources: + items: + $ref: '#/components/schemas/ResourceItemRequestDto' + type: array + title: Resources + description: Resources to assign to the project. + type: object + required: + - resources + title: AddResourceRequestDto + 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: Updated At - description: Timestamp of the last update. - sharing_info: + title: Project Id + description: ID of the deleted project. + deleted_resources: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - additionalProperties: + type: integer + type: object - type: 'null' - description: Present when this project was shared with the authenticated - user. + 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: GetProjectResponseDto - CreateMonitorRequestDto: + title: DeleteProjectResponseDto + EntityType: + type: string + enum: + - company + - person + title: EntityType + description: The type of entity. 'company' for organizations (default), 'person' + for individuals. + ResourceListResponseDto: properties: - reference_job_id: + 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. + type: object + required: + - total + - page + - page_size + - total_pages + - resources + title: ProjectResourceListResponseDto + StatusResponseDto: + properties: + job_id: type: string format: uuid - title: Reference Job Id - description: ID of a completed job whose query/validators/enrichments this - monitor should repeat. + title: Job Id + description: UUID of the job. 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: + status: anyOf: - - type: string + - $ref: '#/components/schemas/PublicJobStatus' - 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: + description: 'Current pipeline stage. Poll until ''completed'' or ''failed''. + Recommended interval: 5 seconds.' + job_info: + $ref: '#/components/schemas/JobIterationInfo' + description: Job progress details; turn is the current 1-indexed fetch band. + steps: anyOf: - items: - type: string - format: uuid + $ref: '#/components/schemas/JobStep' type: array - type: 'null' - 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: 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: + 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 + EnableMonitorResponseDto: + 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: Project Id - description: Project to associate this monitor with. + title: Monitor Id + description: ID of the enabled monitor. type: object required: - - reference_job_id - - schedule - title: CreateMonitorRequestDto - PullMonitorResponseDto: + - success + - message + title: EnableMonitorResponseDto + ManageEntitiesResponseDto: properties: - monitor_id: + dataset_id: type: string format: uuid - title: Monitor Id - description: Unique identifier for the monitor. - cron_expression: - anyOf: - - type: string - - type: 'null' - title: Cron Expression - description: Cron expression for the monitor schedule. - 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: - anyOf: - - $ref: '#/components/schemas/RunInfoDto' - - type: 'null' - description: Execution time range for this monitor. - records: + 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: + - dataset_id + - affected_count + title: ManageEntitiesResponse + 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: Records - description: Total number of records collected across all monitor jobs. + 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: Current monitor status or error message. - all_records: + description: Always 'accepted' on success. + default: accepted + type: object + required: + - job_id + - new_limit + title: ContinueResponseDto + UpdateMonitorRequestDto: + properties: + webhook_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 monitor. + 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: 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: + description: Optional max results per monitor run (min 10, validated against + plan) + schedule: anyOf: - - type: boolean + - type: string - 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: 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: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string - type: 'null' - description: Present when this monitor was shared with the authenticated - user. Omitted when the user owns the monitor. + title: Timezone + 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 - required: - - monitor_id - - reference_job - - status - title: PullMonitorResponseDto - PullResponseDto: + title: UpdateMonitorRequestDto + CreateProjectRequestDto: properties: - job_id: + name: 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: + title: Name + description: Name for the project. + description: anyOf: - type: string - type: 'null' - title: Context - description: Optional context provided at submission time. - validators: + title: Description + description: Optional description. + type: object + required: + - name + title: CreateProjectRequestDto + ProjectListResponseDto: + properties: + 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/ValidatorSchema' + $ref: '#/components/schemas/ProjectResponseDto' type: array - title: Validators - description: Validators applied to candidate articles. - default: [] - enrichments: + title: Projects + description: Projects on this page. + type: object + required: + - total + - page + - page_size + - total_pages + - projects + title: ProjectListResponseDto + ListUserJobsResponseDto: + properties: + total: + type: integer + title: Total + description: Total number of jobs for this user. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of jobs per page. + total_pages: + type: integer + title: Total Pages + description: Total number of pages available. + jobs: items: - $ref: '#/components/schemas/EnrichmentSchema' + $ref: '#/components/schemas/UserJobResponseDto' 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'. - job_info: - $ref: '#/components/schemas/JobIterationInfo' - description: Job progress details; turn is the current 1-indexed fetch band. - error: - anyOf: - - type: string - - type: 'null' - title: Error - description: Human-readable error message. Present only when status == 'failed'. - duration: + title: Jobs + description: Array of user jobs on this page. + type: object + required: + - total + - page + - page_size + - total_pages + - jobs + title: ListUserJobsResponseDto + 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 + DatasetResponseDto: + properties: + id: + type: string + format: uuid + title: Id + description: Unique identifier of the dataset. + organization_id: + type: string + title: Organization Id + description: Organization that owns this dataset. + name: + type: string + title: Name + description: Dataset name. + description: 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 (1-indexed). - default: 1 - page_size: - type: integer - minimum: 1.0 - title: Page Size - description: Number of records per page. - default: 10 - total_pages: + title: Description + description: Optional description. + entity_count: type: integer - minimum: 0.0 - title: Total Pages - description: Total pages available. + title: Entity Count + description: Total number of entities in this dataset. default: 0 - limit: + entity_status_breakdown: + additionalProperties: + type: integer + type: object + title: Entity Status Breakdown + description: Count of entities grouped by processing status. + health_score: anyOf: - - type: integer + - type: number - 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: + title: Health Score + description: Overall health score of the dataset. + health_breakdown: + additionalProperties: + type: number + type: object + title: Health Breakdown + description: Health scores broken down by attribute. + latest_status: anyOf: - - items: - type: string - format: uuid - type: array + - type: string - 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: + title: Latest Status + description: Most recent processing status of the dataset. + created_by_user_id: anyOf: - - items: - $ref: '#/components/schemas/ConnectedDatasetDto' - type: array + - type: string - type: 'null' - title: Connected Datasets - description: Datasets used to narrow retrieval scope, each with id and name. - is_all_news_query: + title: Created By User Id + description: ID of the user who created this dataset. + sharing_info: anyOf: - - type: boolean + - $ref: '#/components/schemas/SharingInfoDto' - type: 'null' - title: Is All News Query - description: True when the query was submitted as an all-news (watchlist-generic) - query. - source_groups: + description: Present when this dataset was shared with the authenticated + user. + created_at: anyOf: - - items: - $ref: '#/components/schemas/SourceGroupRefDto' - type: array + - type: string + format: date-time - type: 'null' - title: Source Groups - description: Source groups attached to this job, each with slug, name, and - description. - sharing_info: + title: Created At + description: Timestamp of when the dataset was created. + updated_at: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string + format: date-time - type: 'null' - description: Present when the job was shared with the calling user (not - their own). + title: Updated At + description: Timestamp of when the dataset was last updated. type: object required: - - job_id - title: PullJobResponseDto - SubmitRequestDto: + - id + - organization_id + - name + title: DatasetResponse + CreateProjectResponseDto: 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. + project_id: anyOf: - type: string + format: uuid - type: 'null' - title: Schema - description: 'Advanced: custom JSON schema string that overrides the default - extraction schema. Use POST /initialize to discover a suitable schema.' - context: + title: Project Id + description: Project identifier. + name: anyOf: - type: string - type: 'null' - title: Context - description: Additional context to sharpen the search scope (geography, - industry, time frame, etc.). - limit: + title: Name + description: Name of the created project. + type: object + required: + - success + - message + title: CreateProjectResponseDto + UpdateWebhookRequestDto: + properties: + name: anyOf: - - type: integer - minimum: 10.0 + - type: string - 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. - start_date: + title: Name + description: Updated webhook name. + url: 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. - end_date: + title: Url + description: Updated webhook endpoint URL. + type: anyOf: - - type: string - format: date-time + - $ref: '#/components/schemas/WebhookType' - type: 'null' - title: End Date - description: Latest article date. Cannot be provided without start_date. - validators: + description: Updated webhook target type. + delivery_mode: anyOf: - - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array + - $ref: '#/components/schemas/DeliveryMode' - type: 'null' - 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: + description: Updated delivery mode. + method: anyOf: - - items: - $ref: '#/components/schemas/EnrichmentSchema' - type: array + - $ref: '#/components/schemas/HttpMethod' - type: 'null' - title: Enrichments - description: Custom extraction fields added to each result record under - enrichments.. Provide at least one item or omit entirely. - mode: + description: Updated HTTP method. + headers: anyOf: - - $ref: '#/components/schemas/ProcessingMode' + - additionalProperties: + type: string + type: object - 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: + title: Headers + description: Updated HTTP headers. + params: anyOf: - - items: + - additionalProperties: type: string - format: uuid - type: array + type: object - 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: + title: Params + description: Updated query string parameters. + auth: anyOf: - - type: integer - maximum: 10.0 - minimum: 1.0 + - 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: 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: + 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/EntityAssociationType' + - $ref: '#/components/schemas/FormatterConfigDto' - 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: + description: Updated custom formatter configuration. + is_active: anyOf: - - items: - type: string - format: uuid - type: array + - type: boolean - type: 'null' - title: Webhook Ids - description: Webhook IDs to notify when the job completes. Max 5 per job. - project_id: + title: Is Active + description: Set to true to activate or false to deactivate. + type: object + title: UpdateWebhookRequestDto + Ownership: + 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. + 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 + type: object + required: + - webhook_id + - total + - page + - page_size + - items + title: WebhookHistoryByWebhookDto + DeleteJobResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the delete operation succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable result message. + job_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 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. + title: Job Id + description: ID of the deleted job. Null on failure. 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 - CsvUploadCreateResponseDto: + - success + - message + title: DeleteJobResponseDto + CreateEntitiesBatchRequestDto: 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. + entities: + items: + $ref: '#/components/schemas/CreateEntityRequestDto' + type: array + title: Entities + description: Array of entities to create. type: object required: - - dataset_id - - dataset_name - - entities_created - - validation_report - title: CreateDatasetCsvResponse + - entities + title: CreateEntitiesBatchRequest EntityResponseDto: properties: id: @@ -3506,203 +3731,129 @@ components: - name - status title: EntityResponse - GetWebhookResponseDto: + DatasetSortBy: + type: string + enum: + - name + - created_at + - status + title: DatasetSortBy + description: Fields available for sorting dataset list results. + ListMonitorJobsResponseDto: 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 - ProjectOverviewResponseDto: - properties: - project_id: + monitor_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. + title: Monitor Id + description: Monitor identifier. + sort_order: + type: string + title: Sort Order + description: Sort order applied to the job list. + total_jobs: + type: integer + title: Total Jobs + description: Total number of jobs executed by this monitor. + jobs: + items: + $ref: '#/components/schemas/MonitorJobItemResponseDto' + type: array + title: Jobs + description: Array of monitor job executions. type: object required: - - project_id - - overview - title: ProjectOverviewResponseDto - EnableMonitorResponseDto: + - monitor_id + - sort_order + - total_jobs + title: ListMonitorJobsResponseDto + UpdateMonitorResponseDto: 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 enabled monitor. - type: object - required: - - success - - message - title: EnableMonitorResponseDto - DatasetListResponseDto: - properties: - 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 - description: Number of datasets per page. - type: object - required: - - datasets - - total - - page - - page_size - title: DatasetListResponse - Ownership: - 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. - RemoveResourceResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: + description: Monitor identifier. + status: type: string - title: Message - description: Human-readable result message. - type: object - required: - - success - - message - title: RemoveResourceResponseDto - ListWebhookResourcesResponseDto: - properties: - 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. + title: Status + description: Confirmation message. + default: Monitor updated Successfully type: object - required: - - total - - page - - page_size - - total_pages - - resources - title: ListWebhookResourcesResponseDto - CreateProjectRequestDto: + title: UpdateMonitorResponseDto + UpdateDatasetRequestDto: properties: name: - type: string + anyOf: + - type: string + - type: 'null' title: Name - description: Name for the project. + description: Updated dataset name. description: anyOf: - type: string - type: 'null' title: Description - description: Optional description. + description: Updated description. type: object - required: - - name - title: CreateProjectRequestDto - UpdateProjectRequestDto: + title: UpdateDatasetRequest + CreateMonitorResponseDto: properties: - name: - anyOf: - - type: string - - type: 'null' - title: Name - description: New name for the project. - description: + monitor_id: anyOf: - type: string + format: uuid - type: 'null' - title: Description - description: New description for the project. + 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: UpdateProjectRequestDto - DatasetStatusHistoryResponseDto: + title: CreateMonitorResponseDto + SuggestInitializeRequestDto: properties: - dataset_id: + query: 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. + 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 + - type: 'null' + title: Context + description: Optional context string that sharpens the suggested fields. + example: Focus on low-cost carriers. + connected_dataset_ids: + anyOf: + - items: + type: string + format: uuid + type: array + - type: 'null' + title: Connected Dataset Ids + description: Optional list of watchlist dataset IDs connected to this job. + fetch_all_watchlist_news: + anyOf: + - type: boolean + - type: 'null' + title: Fetch All Watchlist News + description: When true, returns generic news validators and enrichments + suitable for watchlist-based article collection instead of query-specific + fields. type: object required: - - dataset_id - - history - title: DatasetStatusHistoryResponse - DisableMonitorResponseDto: + - query + title: InitializeRequestDto + example: + context: Focus on low-cost carriers. + query: Which airlines expanded their routes in Asia? + GetWebhookResponseDto: properties: success: type: boolean @@ -3711,204 +3862,179 @@ components: message: type: string title: Message - description: Human-readable success message. - monitor_id: + description: Human-readable result message. + webhook: anyOf: - - type: string - format: uuid + - $ref: '#/components/schemas/WebhookResponseDto' - type: 'null' - title: Monitor Id - description: ID of the disabled monitor. + description: Webhook details. type: object required: - success - message - title: DisableMonitorResponseDto - Body_uploadCSVToDataset: + title: GetWebhookResponseDto + PullResponseDto: properties: - file: + job_id: type: string - format: binary - title: File - type: object - required: - - file - title: Body_uploadCSVToDataset - CreateEntitiesBatchResponseDto: - properties: - 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 - 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.' - UpdateWebhookRequestDto: - properties: - name: + format: uuid + title: Job Id + description: UUID of the job. + query: anyOf: - type: string - type: 'null' - title: Name - description: Updated webhook name. - url: + title: Query + description: Original query submitted for this job. + context: anyOf: - type: string - type: 'null' - title: Url - description: Updated webhook endpoint URL. - type: + 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/WebhookType' + - $ref: '#/components/schemas/PublicJobStatus' - type: 'null' - description: Updated webhook target type. - delivery_mode: + description: Current pipeline stage. Results may be partial while status + != 'completed'. + job_info: + $ref: '#/components/schemas/JobIterationInfo' + description: Job progress details; turn is the current 1-indexed fetch band. + error: anyOf: - - $ref: '#/components/schemas/DeliveryMode' + - type: string - type: 'null' - description: Updated delivery mode. - method: + title: Error + description: Human-readable error message. Present only when status == 'failed'. + duration: anyOf: - - $ref: '#/components/schemas/HttpMethod' + - type: string - type: 'null' - description: Updated HTTP method. - headers: + title: Duration + description: Wall-clock processing time, e.g. '1m 23s'. + candidate_records: anyOf: - - additionalProperties: - type: string - type: object + - type: integer - type: 'null' - title: Headers - description: Updated HTTP headers. - params: + title: Candidate Records + description: Total articles retrieved before validator filtering. + valid_records: anyOf: - - additionalProperties: - type: string - type: object + - type: integer - type: 'null' - title: Params - description: Updated query string parameters. - auth: + 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: - - 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: integer - type: 'null' - title: Auth - description: 'Authentication forwarded with each delivery. Supported types: - ''bearer'' (token), ''api_key'' (header + value), ''basic'' (username - + password).' - formatter_config: + title: Progress Validated + description: Running count of validated records while status == 'enriching'. + date_range: anyOf: - - $ref: '#/components/schemas/FormatterConfigDto' + - $ref: '#/components/schemas/DateRangeDto' - type: 'null' - description: Updated custom formatter configuration. - is_active: + description: Effective date range of the retrieved articles. + all_records: anyOf: - - type: boolean + - items: + $ref: '#/components/schemas/ArticleRecordDto' + type: array - type: 'null' - title: Is Active - description: Set to true to activate or false to deactivate. - type: object - title: UpdateWebhookRequestDto - ListUserJobsResponseDto: - properties: - total: - type: integer - title: Total - description: Total number of jobs for this user. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of jobs per page. - total_pages: - type: integer - title: Total Pages - description: Total number of pages available. - jobs: - items: - $ref: '#/components/schemas/UserJobResponseDto' - type: array - title: Jobs - description: Array of user jobs on this page. - type: object - required: - - total - - page - - page_size - - total_pages - - jobs - title: ListUserJobsResponseDto - ListDatasetEntitiesRequestDto: - properties: + 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: The page number to retrieve. + description: Current page number (1-indexed). 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: + 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: anyOf: - - type: string + - type: integer - type: 'null' - title: Search - description: Filters entities by name using case-insensitive substring match. - status: + 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: - - $ref: '#/components/schemas/EntityStatus' + - items: + type: string + format: uuid + type: array - type: 'null' - description: Filter entities by processing status. - entity_type: + title: Connected Dataset Ids + description: 'Deprecated: use connected_datasets instead. Dataset IDs that + were used to narrow retrieval scope.' + deprecated: true + connected_datasets: anyOf: - - $ref: '#/components/schemas/EntityType' + - items: + $ref: '#/components/schemas/ConnectedDatasetDto' + type: array - 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 + 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 - title: ListDatasetEntitiesRequest - UpdateProjectResponseDto: + required: + - job_id + title: PullJobResponseDto + UpdateWebhookResponseDto: properties: success: type: boolean @@ -3918,18 +4044,158 @@ components: type: string title: Message description: Human-readable result message. - project_id: + webhook: anyOf: - - type: string - format: uuid + - $ref: '#/components/schemas/WebhookResponseDto' - type: 'null' - title: Project Id - description: Project identifier. + description: Updated webhook details. type: object required: - success - message - title: UpdateProjectResponseDto + title: UpdateWebhookResponseDto + RemoveResourceResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable result message. + type: object + required: + - success + - message + title: RemoveResourceResponseDto + 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 + 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: Cron Expression + description: Cron expression for the monitor schedule. + 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: + anyOf: + - $ref: '#/components/schemas/RunInfoDto' + - type: 'null' + description: Execution time range for this monitor. + records: + anyOf: + - type: integer + - type: 'null' + 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/MonitorRecordDto' + type: array + - type: 'null' + 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: + - monitor_id + - reference_job + - status + title: PullMonitorResponseDto + DeleteMonitorResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the delete operation succeeded; false otherwise. + message: + 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 monitor. Null on failure. + type: object + required: + - success + - message + title: DeleteMonitorResponseDto CreateEntityRequestDto: properties: name: @@ -3966,111 +4232,17 @@ components: required: - name title: CreateEntityRequest - ListMonitorJobsResponseDto: - properties: - monitor_id: - type: string - format: uuid - title: Monitor Id - description: Monitor identifier. - sort_order: - type: string - title: Sort Order - description: Sort order applied to the job list. - total_jobs: - type: integer - title: Total Jobs - description: Total number of jobs executed by this monitor. - jobs: - items: - $ref: '#/components/schemas/MonitorJobItemResponseDto' - type: array - title: Jobs - description: Array of monitor job executions. - type: object - required: - - monitor_id - - sort_order - - total_jobs - title: ListMonitorJobsResponseDto - CreateWebhookRequestDto: + TestWebhookRequestDto: properties: - name: - type: string - title: Name - description: Human-readable label for this webhook. - example: Layoffs Alert - url: - type: string - title: Url - description: Destination URL that receives the payload. - example: https://hooks.slack.com/services/T000/B000/xxxx - type: - $ref: '#/components/schemas/WebhookType' - default: generic - delivery_mode: - $ref: '#/components/schemas/DeliveryMode' - description: '''full'' delivers the entire result set in one call; ''per_record'' - sends one call per article.' - default: full - method: - $ref: '#/components/schemas/HttpMethod' - description: HTTP method used for delivery. - default: POST - headers: - additionalProperties: - type: string - type: object - title: Headers - description: Custom HTTP headers forwarded with each delivery. - default: {} - params: - additionalProperties: - type: string - type: object - title: Params - description: Query parameters appended to the webhook URL. - default: {} - 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: Custom payload formatter. Required when type is 'custom'. - project_id: + payload: anyOf: - - type: string - format: uuid + - additionalProperties: true + type: object - type: 'null' - title: Project Id - description: Optional project ID to associate this webhook with immediately - upon creation. + title: Payload + description: Custom payload to send in the test request. type: object - required: - - name - - url - title: CreateWebhookRequestDto - example: - delivery_mode: full - name: Layoffs Alert - type: slack - url: https://hooks.slack.com/services/T000/B000/xxxx + title: TestWebhookRequestDto CreateEntityResponseDto: properties: id: @@ -4088,118 +4260,134 @@ components: required: - id title: CreateEntityResponse - 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 - SortOrder: - type: string - enum: - - asc - - desc - title: SortOrder - description: Sort direction for list results. 'asc' for ascending (oldest first), - 'desc' for descending (newest first). - 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 - type: object - required: - - webhook_id - - total - - page - - page_size - - items - title: WebhookHistoryByWebhookDto - DeleteJobResponseDto: + GetProjectResponseDto: properties: success: type: boolean title: Success - description: True if the delete operation succeeded; false otherwise. + description: True if the operation succeeded; false otherwise. message: type: string title: Message description: Human-readable result message. - job_id: + project_id: anyOf: - type: string format: uuid - type: 'null' - title: Job Id - description: ID of the deleted job. Null on failure. - type: object - required: - - success - - message - title: DeleteJobResponseDto - DeleteMonitorResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the delete operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - monitor_id: + title: Project Id + description: Project identifier. + name: anyOf: - type: string - format: uuid - type: 'null' - title: Monitor Id - description: ID of the deleted monitor. Null on failure. + 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. type: object required: - success - message - title: DeleteMonitorResponseDto - SuggestInitializeRequestDto: + title: GetProjectResponseDto + SubmitRequestDto: properties: query: type: string + minLength: 1 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? + description: Natural-language question. Keywords and search queries are + extracted automatically. + schema: + anyOf: + - type: string + - type: 'null' + 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 string that sharpens the suggested fields. - example: Focus on low-cost carriers. + 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. + 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. + end_date: + anyOf: + - type: string + format: date-time + - type: 'null' + title: End Date + description: Latest article date. Cannot be provided without start_date. + validators: + anyOf: + - items: + $ref: '#/components/schemas/ValidatorSchema' + type: array + - type: 'null' + 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/EnrichmentSchema' + type: array + - type: 'null' + 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: @@ -4208,130 +4396,80 @@ components: type: array - type: 'null' title: Connected Dataset Ids - description: Optional list of watchlist dataset IDs connected to this job. - fetch_all_watchlist_news: + 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: boolean + - type: integer + maximum: 10.0 + minimum: 1.0 - type: 'null' - title: Fetch All Watchlist News - description: When true, returns generic news validators and enrichments - suitable for watchlist-based article collection instead of query-specific - fields. - type: object - required: - - query - title: InitializeRequestDto - example: - context: Focus on low-cost carriers. - query: Which airlines expanded their routes in Asia? - 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. + 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: ID of the deleted project. - deleted_resources: + 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: - - additionalProperties: - type: integer - type: object + - items: + type: string + type: array - 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: DeleteProjectResponseDto - ListWebhooksResponseDto: - properties: - total: - type: integer - title: Total - description: Total number of webhooks. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of webhooks per page. - total_pages: - type: integer - 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. + 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: - - total - - page - - page_size - - total_pages - - webhooks - title: ListWebhooksResponseDto - 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: 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: 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 - UpdateWebhookResponseDto: + - 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 + UpdateProjectResponseDto: properties: success: type: boolean @@ -4341,51 +4479,42 @@ 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 - ContinueRequestDto: + title: UpdateProjectResponseDto + CreateEntitiesBatchResponseDto: 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 + 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: - - job_id - title: ContinueRequestDto - example: - job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - new_limit: 250 - WebhookHistoryByResourceDto: + - entities + - count + title: CreateEntitiesBatchResponse + ListSourceGroupsApiResponseDto: 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 + source_groups: + items: + $ref: '#/components/schemas/SourceGroupApiResponseDto' + type: array + title: Source Groups total: type: integer title: Total @@ -4395,32 +4524,25 @@ components: page_size: type: integer title: Page Size - items: - items: - $ref: '#/components/schemas/WebhookStatusItemDto' - type: array - title: Items type: object required: - - resource_type - - resource_id + - source_groups - total - page - page_size - - items - title: WebhookHistoryByResourceDto - DatasetEntityListResponseDto: + title: ListSourceGroupsApiResponseDto + EntityListResponseDto: properties: entities: items: - $ref: '#/components/schemas/EntitySummaryDto' + $ref: '#/components/schemas/EntityResponseDto' type: array title: Entities - description: Array of entity summary objects for this page. + description: Array of entity objects for this page. total: type: integer title: Total - description: Total number of entities in the dataset. + description: Total number of entities matching the filter criteria. page: type: integer title: Page @@ -4435,13 +4557,50 @@ components: - total - page - page_size - title: DatasetEntityListResponse - ListMonitorsResponseDto: + title: EntityListResponse + MonitorStatusHistoryResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the request succeeded; false otherwise. + message: + anyOf: + - type: string + - type: 'null' + title: Message + description: Optional message. Null on success. + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: Monitor identifier. Null on failure. + total_statuses: + anyOf: + - type: integer + - type: 'null' + title: Total Statuses + description: Total number of status entries in the history. + statuses: + anyOf: + - items: + $ref: '#/components/schemas/MonitorStatusEntryDto' + type: array + - type: 'null' + title: Statuses + description: Full status history, ordered newest to oldest. + type: object + required: + - success + title: MonitorStatusHistoryResponseDto + ListWebhooksResponseDto: properties: total: type: integer title: Total - description: Total number of monitors for this user. + description: Total number of webhooks. page: type: integer title: Page @@ -4449,198 +4608,198 @@ components: page_size: type: integer title: Page Size - description: Number of 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 monitor summaries. + title: Webhooks + description: Array of webhook objects on this page. type: object required: - total - page - page_size - total_pages - - monitors - title: ListMonitorsResponseDto - AssignWebhookResourceResponseDto: + - webhooks + title: ListWebhooksResponseDto + WebhookHistoryByResourceDto: properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - 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: - anyOf: - - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' - - type: 'null' - description: Created or existing resource mapping. - type: object - required: - - success - title: AssignWebhookResourceResponseDto - DatasetSortBy: - type: string - enum: - - name - - created_at - - status - title: DatasetSortBy - description: Fields available for sorting dataset list results. - 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. - DatasetEntityIdsRequestDto: - properties: - entity_ids: + mode: + type: string + const: resource + title: Mode + default: resource + resource_type: + $ref: '#/components/schemas/MappableResourceType' + resource_id: + type: string + format: uuid + title: Resource Id + total: + type: integer + title: Total + page: + type: integer + title: Page + page_size: + type: integer + title: Page Size + items: items: - type: string - format: uuid + $ref: '#/components/schemas/WebhookStatusItemDto' type: array - title: Entity Ids - description: List of entity IDs to add or remove. + title: Items type: object required: - - entity_ids - title: DatasetEntityIdsRequest - CreateDatasetRequestDto: + - resource_type + - resource_id + - total + - page + - page_size + - items + title: WebhookHistoryByResourceDto + ListDatasetEntitiesRequestDto: properties: - name: - type: string - minLength: 1 - title: Name - description: Name for the dataset. - description: + 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: Description - description: Optional description. - entity_ids: + title: Search + description: Filters entities by name using case-insensitive substring match. + status: anyOf: - - items: - type: string - format: uuid - type: array + - $ref: '#/components/schemas/EntityStatus' - type: 'null' - title: Entity Ids - description: IDs of existing entities to include in the dataset. - project_id: + description: Filter entities by processing status. + entity_type: anyOf: - - type: string - format: uuid + - $ref: '#/components/schemas/EntityType' - type: 'null' - title: Project Id - description: Project to assign this dataset to. + 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 - required: - - name - title: CreateDatasetRequest - AssignWebhookResourceRequestDto: + title: ListDatasetEntitiesRequest + CsvUploadToExistingResponseDto: properties: - resource_type: - $ref: '#/components/schemas/MappableResourceType' - description: Type of resource to assign. - resource_id: + dataset_id: type: string format: uuid - title: Resource Id - description: ID of the resource to assign. + 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. type: object required: - - resource_type - - resource_id - title: AssignWebhookResourceRequestDto - EntitySortBy: + - dataset_id + - entities_created + - validation_report + title: UploadCsvToDatasetResponse + ProjectResourceTypeEnum: type: string enum: - - created_at - - name - - status - title: EntitySortBy - description: Fields available for sorting entity list results. - SuggestInitializeResponseDto: + - job + - monitor + - dataset + - monitor_group + - webhook + title: ProjectResourceTypeEnum + description: Resource type for project association. + DisableMonitorResponseDto: properties: - query: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: 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: + title: Message + description: Human-readable success message. + monitor_id: anyOf: - type: string - format: date-time + format: uuid - 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: + title: Monitor Id + description: ID of the disabled monitor. + type: object + required: + - success + - message + title: DisableMonitorResponseDto + ListWebhookResourcesResponseDto: + properties: + 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/EnrichmentSchema' + $ref: '#/components/schemas/WebhookResourceMappingResponseDto' 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: Resources + description: Array of resource mappings on this page. type: object required: - - query - title: InitializeResponseDto - EntityListResponseDto: + - total + - page + - page_size + - total_pages + - resources + title: ListWebhookResourcesResponseDto + DatasetEntityListResponseDto: properties: entities: items: - $ref: '#/components/schemas/EntityResponseDto' + $ref: '#/components/schemas/EntitySummaryDto' type: array title: Entities - description: Array of entity objects for this page. + description: Array of entity summary objects for this page. total: type: integer title: Total - description: Total number of entities matching the filter criteria. + description: Total number of entities in the dataset. page: type: integer title: Page @@ -4655,9 +4814,25 @@ components: - total - page - page_size - title: EntityListResponse - EnableMonitorRequestDto: - properties: + title: DatasetEntityListResponse + 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. + EntitySortBy: + type: string + enum: + - created_at + - name + - status + title: EntitySortBy + description: Fields available for sorting entity list results. + EnableMonitorRequestDto: + properties: backfill: anyOf: - type: boolean @@ -4669,303 +4844,224 @@ components: type: object title: EnableMonitorRequestDto description: Optional body for POST /{monitor_id}/enable. - DatasetResponseDto: + DatasetStatusHistoryResponseDto: properties: - id: + dataset_id: type: string format: uuid - title: Id - description: Unique identifier of the dataset. - organization_id: + title: Dataset Id + description: Dataset identifier. + history: + items: + $ref: '#/components/schemas/DatasetStatusEntryDto' + type: array + title: History + description: Status change entries, ordered oldest to newest. + type: object + required: + - dataset_id + - history + title: DatasetStatusHistoryResponse + CreateMonitorRequestDto: + properties: + reference_job_id: type: string - title: Organization Id - description: Organization that owns this dataset. - name: + 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: Name - description: Dataset name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Optional description. - entity_count: - type: integer - title: Entity Count - description: Total number of entities in this dataset. - default: 0 - entity_status_breakdown: - additionalProperties: - type: integer - type: object - title: Entity Status Breakdown - description: Count of entities grouped by processing status. - health_score: - anyOf: - - type: number - - type: 'null' - title: Health Score - description: Overall health score of the dataset. - health_breakdown: - additionalProperties: - type: number - type: object - title: Health Breakdown - description: Health scores broken down by attribute. - latest_status: + 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: Latest Status - description: Most recent processing status of the dataset. - created_by_user_id: + 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: - - type: string + - items: + type: string + format: uuid + type: array - type: 'null' - title: Created By User Id - description: ID of the user who created this dataset. - sharing_info: + title: Webhook Ids + description: Webhook IDs to notify on each run completion. Max 5 per monitor. + limit: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: integer + minimum: 10.0 - type: 'null' - description: Present when this dataset was shared with the authenticated - user. - created_at: + title: Limit + description: Max results per monitor run. Minimum 10. Validated against + plan limit. + example: 50 + backfill: anyOf: - - type: string - format: date-time + - type: boolean - type: 'null' - title: Created At - description: Timestamp of when the dataset was created. - updated_at: + 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: - type: string - format: date-time + format: uuid - type: 'null' - title: Updated At - description: Timestamp of when the dataset was last updated. + title: Project Id + description: Project to associate this monitor with. type: object required: - - id - - organization_id - - name - title: DatasetResponse - ListSourceGroupsApiResponseDto: + - reference_job_id + - schedule + title: CreateMonitorRequestDto + SubmitResponseDto: properties: - source_groups: + 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 + DatasetEntityIdsRequestDto: + properties: + entity_ids: items: - $ref: '#/components/schemas/SourceGroupApiResponseDto' + type: string + format: uuid type: array - title: Source Groups + title: Entity Ids + description: List of entity IDs to add or remove. + type: object + required: + - entity_ids + title: DatasetEntityIdsRequest + Body_uploadCSVToDataset: + properties: + file: + type: string + format: binary + title: File + type: object + required: + - file + title: Body_uploadCSVToDataset + ListWebhooksForResourceResponseDto: + properties: + total: + type: integer + title: Total + description: Total number of webhooks assigned to this resource. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of webhooks per page. + total_pages: + type: integer + title: Total Pages + description: Total number of pages available. + webhooks: + items: + $ref: '#/components/schemas/WebhookResponseDto' + type: array + title: Webhooks + description: Array of webhook objects. + type: object + required: + - total + - page + - page_size + - total_pages + - webhooks + title: ListWebhooksForResourceResponseDto + 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.' + DatasetListResponseDto: + properties: + 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 + description: Number of datasets per page. type: object required: - - source_groups + - datasets - total - page - page_size - title: ListSourceGroupsApiResponseDto - Body_createDatasetFromCsv: + title: DatasetListResponse + CreateDatasetRequestDto: properties: - file: - type: string - format: binary - title: File name: type: string + minLength: 1 title: Name + description: Name for the dataset. description: - type: string + anyOf: + - type: string + - type: 'null' title: Description - project_id: - type: string - title: Project Id - type: object - required: - - file - - name - title: Body_createDatasetFromCsv - MonitorStatusHistoryResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the request succeeded; false otherwise. - message: - anyOf: - - type: string - - type: 'null' - title: Message - description: Optional message. Null on success. - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: Monitor identifier. Null on failure. - total_statuses: - anyOf: - - type: integer - - type: 'null' - title: Total Statuses - description: Total number of status entries in the history. - statuses: + description: Optional description. + entity_ids: anyOf: - items: - $ref: '#/components/schemas/MonitorStatusEntryDto' + type: string + format: uuid type: array - type: 'null' - title: Statuses - description: Full status history, ordered newest to oldest. - type: object - required: - - success - title: MonitorStatusHistoryResponseDto - 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 - ProjectListResponseDto: - properties: - 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: - - total - - page - - page_size - - total_pages - - projects - title: ProjectListResponseDto - CreateEntitiesBatchRequestDto: - properties: - entities: - items: - $ref: '#/components/schemas/CreateEntityRequestDto' - type: array - title: Entities - description: Array of entities to create. - type: object - required: - - entities - title: CreateEntitiesBatchRequest - UpdateMonitorResponseDto: - properties: - monitor_id: + title: Entity Ids + description: IDs of existing entities to include in the dataset. + project_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 - UpdateDatasetRequestDto: - properties: - name: - anyOf: - - type: string - - type: 'null' - title: Name - description: Updated dataset name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Updated description. - type: object - title: UpdateDatasetRequest - ListWebhooksForResourceResponseDto: - properties: - total: - type: integer - title: Total - description: Total number of webhooks assigned to this resource. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of webhooks per page. - total_pages: - type: integer - title: Total Pages - description: Total number of pages available. - webhooks: - items: - $ref: '#/components/schemas/WebhookResponseDto' - type: array - title: Webhooks - description: Array of webhook objects. + title: Project Id + description: Project to assign this dataset to. type: object required: - - total - - page - - page_size - - total_pages - - webhooks - title: ListWebhooksForResourceResponseDto + - name + title: CreateDatasetRequest UpdateEntityRequestDto: properties: name: @@ -4994,22 +5090,16 @@ components: description: Updated type-specific attributes. type: object title: UpdateEntityRequest - ManageEntitiesResponseDto: - properties: - dataset_id: - 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. - type: object - required: - - dataset_id - - affected_count - title: ManageEntitiesResponse + 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.' CreateWebhookResponseDto: properties: success: @@ -5030,117 +5120,27 @@ components: - success - message title: CreateWebhookResponseDto - ProjectResourceTypeEnum: - type: string - enum: - - job - - monitor - - dataset - - monitor_group - - webhook - title: ProjectResourceTypeEnum - description: Resource type for project association. - CreateMonitorResponseDto: + ProjectOverviewResponseDto: properties: - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: Monitor identifier. Null if creation failed. - status: + project_id: type: string - title: Status - description: Creation status or error message. - default: Monitor Created Successfully + 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 - title: CreateMonitorResponseDto - 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/PublicJobStatus' - - type: 'null' - description: 'Current pipeline stage. Poll until ''completed'' or ''failed''. - Recommended interval: 5 seconds.' - job_info: - $ref: '#/components/schemas/JobIterationInfo' - description: Job progress details; turn is the current 1-indexed fetch band. - 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. - type: object - required: - - job_id - title: StatusResponseDto - 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.' - AddResourceRequestDto: - properties: - resources: - items: - $ref: '#/components/schemas/ResourceItemRequestDto' - type: array - title: Resources - description: Resources to assign to the project. - type: object - required: - - resources - title: AddResourceRequestDto - 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. - type: object - required: - - total - - page - - page_size - - total_pages - - resources - title: ProjectResourceListResponseDto - GetFeaturesResponse: + required: + - project_id + - overview + title: ProjectOverviewResponseDto + GetFeaturesResponse: properties: features: items: @@ -5152,6 +5152,35 @@ components: required: - features title: GetPlanLimitsResponseDto + ValidationError: + properties: + loc: + items: + anyOf: + - type: string + - type: integer + type: array + title: Location + msg: + type: string + title: Message + type: + type: string + title: Error Type + type: object + required: + - loc + - msg + - type + title: ValidationError + QueryStatus: + type: string + enum: + - good + - needs_work + - critical + title: QueryStatus + description: Query quality assessment levels IssueType: type: string enum: @@ -5186,35 +5215,6 @@ components: - message title: Suggestion description: Actionable recommendation for query improvement - QueryStatus: - type: string - enum: - - good - - needs_work - - critical - title: QueryStatus - description: Query quality assessment levels - ValidationError: - properties: - loc: - items: - anyOf: - - type: string - - type: integer - type: array - title: Location - msg: - type: string - title: Message - type: - type: string - title: Error Type - type: object - required: - - loc - - msg - - type - title: ValidationError CsvValidationReportDto: properties: total_rows: @@ -5243,139 +5243,175 @@ components: - skipped_count - skipped_rows title: ValidationReport - ResourceResultResponseDto: + HttpMethod: + type: string + enum: + - GET + - POST + - PUT + - PATCH + - DELETE + title: HttpMethod + description: HTTP method used for webhook delivery. + BearerAuthDto: properties: - resource_type: + type: type: string - title: Resource Type - description: Type of the resource. - resource_id: + const: bearer + title: Type + description: Authentication type. + token: type: string - format: uuid - title: Resource Id - description: Resource identifier. - success: - type: boolean - title: Success - description: True if this resource was processed successfully. - message: + title: Token + description: Bearer token value sent in the Authorization header. + type: object + required: + - type + - token + title: BearerAuth + 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. + FormatterConfigDto: + properties: + template: 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 + 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, + application/ld+json, text/html, text/plain, text/xml, application/xml, + text/csv.' + default: application/json + example: application/json type: object required: - - resource_type - - resource_id - - success - - message - title: ResourceResultDto - SharingInfoDto: + - template + title: FormatterConfig + ApiKeyAuthDto: 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: + 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 - title: SharingInfo - MonitorRecordDto: + required: + - type + - header + - value + title: ApiKeyAuth + DeliveryMode: + type: string + enum: + - full + - per_record + title: DeliveryMode + description: Delivery mode for webhook payloads. 'full' delivers the entire + result set in one call; 'per_record' sends one call per article. + BasicAuthDto: properties: - record_id: - anyOf: - - type: string - - type: 'null' - title: Record Id - description: Unique cluster identifier for this record. - record_title: + type: + type: string + const: basic + title: Type + description: Authentication type. + username: + 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 + MonitorListItemResponseDto: + properties: + monitor_id: + type: string + format: uuid + title: Monitor Id + description: Monitor identifier. + reference_job_id: + type: string + format: uuid + title: Reference Job Id + description: Job identifier used as a reference for this monitor. + reference_job_query: + type: string + title: Reference Job Query + description: Plain text query from the reference job. + sharing_info: anyOf: - - type: string + - $ref: '#/components/schemas/SharingInfoDto' - 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: + 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 monitor is currently active; false otherwise. + schedule: anyOf: - - additionalProperties: - type: number - type: object + - type: string - 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: + title: Schedule + description: Cron expression for monitor schedule. + timezone: anyOf: - - items: - $ref: '#/components/schemas/MonitorCitationDto' - type: array + - type: string - type: 'null' - title: Citations - description: Source articles included in this record, with job attribution. - connected_entities: + title: Timezone + description: Timezone for schedule execution. + created_at: anyOf: - - items: - $ref: '#/components/schemas/ConnectedEntityDto' - type: array + - type: string - type: 'null' - title: Connected Entities - description: Entities from connected datasets that matched this record. - added_on: + title: Created At + description: Timestamp of when the monitor was created. + schedule_human_readable: anyOf: - type: string - type: 'null' - title: Added On - description: ISO 8601 timestamp when this record was first added. - updated_on: + title: Schedule Human Readable + description: Monitor schedule in plain text format. + user_key: anyOf: - type: string - type: 'null' - title: Updated On - description: ISO 8601 timestamp when this record was last updated. - type: object - title: MonitorRecord - ConnectedDatasetDto: - properties: - id: - type: string - format: uuid - title: Id - description: Dataset identifier. - name: - type: string - title: Name - description: Dataset name as stored. Check is_deleted to determine whether - the dataset is still active. - is_deleted: - type: boolean - title: Is Deleted - description: True when the dataset has been deleted. - default: false + title: User Key + description: Masked API key associated with this monitor. type: object required: - - id - - name - title: ConnectedDataset + - monitor_id + - reference_job_id + - reference_job_query + - enabled + title: MonitorListItemDto ValidatorSchema: properties: name: @@ -5402,22 +5438,6 @@ components: - description title: ValidatorSchema description: A boolean classifier applied to every candidate article. - 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 EnrichmentSchema: properties: name: @@ -5442,31 +5462,114 @@ components: - type title: EnrichmentSchema description: A custom extraction field added to each validated article. - ReferenceJob: + WebhookResourceMappingResponseDto: properties: - query: + 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: Query - description: Plain text query from the reference job. - context: + title: Assigned At + description: Timestamp of when the resource was assigned. + type: object + required: + - id + - webhook_id + - resource_type + - resource_id + title: WebhookResourceMappingDto + 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: + - resource_type + - resource_id + title: ResourceItemDto + 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: Context - description: Context provided with the reference job query. - source_groups: + title: Name + description: Resource display name. + created_at: anyOf: - - items: - $ref: '#/components/schemas/SourceGroupRefDto' - type: array + - type: string - type: 'null' - title: Source Groups - description: Source groups attached to the reference job, each with slug, - name, and description. + title: Created At + description: Resource creation timestamp. + metadata: + additionalProperties: true + type: object + title: Metadata + description: Additional resource-specific metadata. type: object - title: ReferenceJob + required: + - resource_type + - resource_id + title: ProjectResourceDto + JobIterationInfo: + properties: + turn: + type: integer + title: Turn + description: Current 1-indexed fetch band; unbanded jobs are reported as + turn 1. + default: 1 + type: object + title: JobIterationInfo + 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 PublicJobStatus: type: string enum: @@ -5481,116 +5584,201 @@ components: description: 'Current job processing status. Jobs progress through stages: submitted → analyzing → fetching → clustering → enriching → completed. Later turns repeat fetching, clustering, and enriching.' - DateRangeDto: + ProjectResponseDto: properties: - start_date: + 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: Start Date - description: Inclusive start of the article date range (ISO 8601). - end_date: + 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: End Date - description: Inclusive end of the article date range (ISO 8601). - type: object - title: DateRange - ArticleRecordDto: - properties: - record_id: + title: Created At + description: Project creation timestamp. + updated_at: anyOf: - type: string - type: 'null' - title: Record Id - description: Unique cluster identifier for this record. - record_title: + title: Updated At + description: Timestamp of the last update. + sharing_info: anyOf: - - type: string + - $ref: '#/components/schemas/SharingInfoDto' - 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: + 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 + UserJobResponseDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: Job identifier. + query: + type: string + title: Query + description: Plain text query for this job. + created_at: + type: string + format: date-time + title: Created At + description: Job creation timestamp. + status: + $ref: '#/components/schemas/PublicJobStatus' + description: Current processing status of the job. + job_info: + $ref: '#/components/schemas/JobIterationInfo' + description: Job progress details; turn is the current 1-indexed fetch band. + user_key: + type: string + title: User Key + description: Masked API key that created this job. + sharing_info: anyOf: - - additionalProperties: - type: number - type: object + - $ref: '#/components/schemas/SharingInfoDto' - 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: + description: Present when this job was shared with the authenticated user. + Omitted when the user owns the job. + mode: + $ref: '#/components/schemas/ProcessingMode' + description: Processing mode used for this job. + default: base + type: object + required: + - job_id + - query + - created_at + - status + - user_key + title: UserJob + 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 + SharingInfoDto: + properties: + shared_at: anyOf: - - items: - $ref: '#/components/schemas/CitationDto' - type: array + - type: string + format: date-time - type: 'null' - title: Citations - description: Source articles included in this record. - connected_entities: + title: Shared At + shared_by_user_id: anyOf: - - items: - $ref: '#/components/schemas/ConnectedEntityDto' - type: array + - type: string - type: 'null' - title: Connected Entities - description: Entities from connected datasets that matched this record. - Present only when entity datasets are used. - tags: + title: Shared By User Id + permission: anyOf: - - $ref: '#/components/schemas/EventTagsDto' + - type: string - type: 'null' - description: Fixed-taxonomy classification of the event. Present only for - all-news queries (is_all_news_query == true), and absent for a record - the classifier could not tag. + title: Permission type: object - title: Record - JobIterationInfo: + title: SharingInfo + WebhookStatusItemDto: properties: - turn: + id: type: integer - title: Turn - description: Current 1-indexed fetch band; unbanded jobs are reported as - turn 1. - default: 1 - type: object - title: JobIterationInfo - SourceGroupRefDto: - properties: - slug: + title: Id + webhook_id: type: string - title: Slug - description: Source group slug. - name: + format: uuid + title: Webhook Id + resource_type: + $ref: '#/components/schemas/WebhookHistoryResourceType' + resource_id: type: string - title: Name - description: Source group name. - description: + 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: + type: string + format: date-time + title: Timestamp + delivery_status: + $ref: '#/components/schemas/WebhookDeliveryStatus' + error_message: anyOf: - type: string - type: 'null' - title: Description - description: Source group description. + title: Error Message + warning_message: + anyOf: + - type: string + - type: 'null' + title: Warning Message type: object required: - - slug - - name - title: SourceGroupRef - EntityAssociationType: - type: string - enum: - - mention - - event_associated - title: EntityAssociationType - description: 'How an entity relates to an event: direct actor or merely mentioned.' + - id + - webhook_id + - resource_type + - resource_id + - attempt_number + - timestamp + - delivery_status + title: WebhookStatusItemDto AdditionalAttributesDto: properties: company_attributes: @@ -5601,21 +5789,44 @@ components: additionalProperties: true type: object title: AdditionalAttributes - WebhookResponseDto: + MonitorJobItemResponseDto: properties: - id: + job_id: type: string format: uuid - title: Id - description: Webhook identifier. - name: - type: string - title: Name - description: Webhook name. - url: - type: string - title: Url - description: Webhook endpoint URL. + 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 + WebhookResponseDto: + properties: + id: + type: string + format: uuid + 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 @@ -5698,292 +5909,275 @@ components: - method - is_active title: WebhookDto - WebhookResourceMappingResponseDto: + DateRangeDto: 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: + start_date: 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 - 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: + title: Start Date + description: Inclusive start of the article date range (ISO 8601). + end_date: anyOf: - type: string - format: date-time - type: 'null' - title: Created At - description: Timestamp of when this status was set. + title: End Date + description: Inclusive end of the article date range (ISO 8601). type: object - required: - - status - title: DatasetStatusEntry - 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. - HttpMethod: - type: string - enum: - - GET - - POST - - PUT - - PATCH - - DELETE - title: HttpMethod - description: HTTP method used for webhook delivery. - FormatterConfigDto: + title: DateRange + SourceGroupRefDto: properties: - template: + slug: type: string - title: Template - description: Liquid template string rendered at dispatch time. Maximum 10 - KB. - example: '{"event": "{{ event }}", "count": {{ records_count }}}' - content_type: + title: Slug + description: Source group slug. + name: type: string - title: Content Type - description: 'Content-Type of the rendered output. Supported values: application/json, - application/ld+json, text/html, text/plain, text/xml, application/xml, - text/csv.' - default: application/json - example: application/json + title: Name + description: Source group name. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Source group description. type: object required: - - template - title: FormatterConfig - BearerAuthDto: + - slug + - name + title: SourceGroupRef + ArticleRecordDto: properties: - type: - type: string - const: bearer - title: Type - description: Authentication type. - token: - type: string - title: Token - description: Bearer token value sent in the Authorization header. + 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/CitationDto' + type: array + - type: 'null' + title: Citations + description: Source articles included in this record. + connected_entities: + anyOf: + - items: + $ref: '#/components/schemas/ConnectedEntityDto' + type: array + - type: 'null' + title: Connected Entities + description: Entities from connected datasets that matched this record. + Present only when entity datasets are used. + tags: + anyOf: + - $ref: '#/components/schemas/EventTagsDto' + - type: 'null' + description: Fixed-taxonomy classification of the event. Present only for + all-news queries (is_all_news_query == true), and absent for a record + the classifier could not tag. type: object - required: - - type - - token - title: BearerAuth - ApiKeyAuthDto: + title: Record + ConnectedDatasetDto: properties: - type: - type: string - const: api_key - title: Type - description: Authentication type. - header: + id: type: string - title: Header - description: HTTP header name for the API key, e.g. 'X-API-Key'. - value: + format: uuid + title: Id + description: Dataset identifier. + name: type: string - title: Value - description: API key value. + title: Name + description: Dataset name as stored. Check is_deleted to determine whether + the dataset is still active. + is_deleted: + type: boolean + title: Is Deleted + description: True when the dataset has been deleted. + default: false type: object required: - - type - - header - - value - title: ApiKeyAuth - DeliveryMode: - type: string - enum: - - full - - per_record - title: DeliveryMode - description: Delivery mode for webhook payloads. 'full' delivers the entire - result set in one call; 'per_record' sends one call per article. - BasicAuthDto: + - id + - name + title: ConnectedDataset + MonitorRecordDto: properties: - type: - type: string - const: basic - title: Type - description: Authentication type. - username: - type: string - title: Username - description: Basic auth username. - password: - type: string - title: Password - description: Basic auth password. + 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 - required: - - type - - username - - password - title: BasicAuth - UserJobResponseDto: + title: MonitorRecord + ReferenceJob: properties: - job_id: - type: string - format: uuid - title: Job Id - description: Job identifier. query: - type: string + anyOf: + - type: string + - type: 'null' title: Query - description: Plain text query for this job. - created_at: - type: string - format: date-time - title: Created At - description: Job creation timestamp. - status: - $ref: '#/components/schemas/PublicJobStatus' - description: Current processing status of the job. - job_info: - $ref: '#/components/schemas/JobIterationInfo' - description: Job progress details; turn is the current 1-indexed fetch band. - user_key: - type: string - title: User Key - description: Masked API key that created this job. - sharing_info: + description: Plain text query from the reference job. + context: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string - type: 'null' - description: Present when this job was shared with the authenticated user. - Omitted when the user owns the job. - mode: - $ref: '#/components/schemas/ProcessingMode' - description: Processing mode used for this job. - default: base + 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 - required: - - job_id - - query - - created_at - - status - - user_key - title: UserJob - MonitorJobItemResponseDto: + title: ReferenceJob + RunInfoDto: properties: - job_id: - type: string - format: uuid - title: Job Id - description: Unique identifier for this job execution. - start_date: + first_run: anyOf: - type: string - type: 'null' - title: Start Date - description: Start of the data collection time window for this job execution. - end_date: + title: First Run + description: ISO 8601 timestamp of the first completed run. + last_run: anyOf: - type: string - type: 'null' - title: End Date - description: End of the data collection time window for this job execution. + title: Last Run + description: ISO 8601 timestamp of the most recent completed run. type: object - required: - - job_id - title: MonitorJobItem - WebhookStatusItemDto: + title: RunInfo + EntityAssociationType: + type: string + enum: + - mention + - event_associated + title: EntityAssociationType + description: 'How an entity relates to an event: direct actor or merely mentioned.' + SourceGroupApiResponseDto: properties: - id: - type: integer - title: Id - webhook_id: + slug: type: string - format: uuid - title: Webhook Id - resource_type: - $ref: '#/components/schemas/WebhookHistoryResourceType' - resource_id: + title: Slug + name: type: string - format: uuid - title: Resource Id - additional_info: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Additional Info - status_code: + title: Name + description: anyOf: - - type: integer + - type: string - type: 'null' - title: Status Code - attempt_number: + title: Description + type: object + required: + - slug + - name + title: SourceGroupApiResponseDto + MonitorStatusEntryDto: + properties: + id: type: integer - title: Attempt Number - timestamp: + title: Id + description: Status entry identifier. + status: + type: string + title: Status + description: Type of lifecycle event. + created_at: type: string format: date-time - title: Timestamp - delivery_status: - $ref: '#/components/schemas/WebhookDeliveryStatus' - error_message: - anyOf: - - type: string - - type: 'null' - title: Error Message - warning_message: + title: Created At + description: Timestamp of this event. + additional_information: anyOf: - - type: string + - {} - type: 'null' - title: Warning Message + title: Additional Information + description: Event-specific metadata. Null for created, enable, and disable + events. type: object required: - id - - webhook_id - - resource_type - - resource_id - - attempt_number - - timestamp - - delivery_status - title: WebhookStatusItemDto + - status + - created_at + title: MonitorStatusEntry EntitySummaryDto: properties: id: @@ -6027,273 +6221,254 @@ components: - entity_type - status title: EntitySummary - MonitorListItemResponseDto: + DatasetStatusEntryDto: properties: - monitor_id: - type: string - format: uuid - title: Monitor Id - description: Monitor identifier. - reference_job_id: - type: string - format: uuid - title: Reference Job Id - description: Job identifier used as a reference for this monitor. - reference_job_query: + status: type: string - title: Reference Job Query - description: Plain text query from the reference job. - 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. - enabled: - type: boolean - title: Enabled - description: True if the monitor is currently active; false otherwise. - schedule: - anyOf: - - type: string - - type: 'null' - title: Schedule - description: Cron expression for monitor schedule. - timezone: + title: Status + description: Dataset processing status. + additional_information: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Timezone - description: Timezone for schedule execution. + 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 the monitor was created. - schedule_human_readable: - anyOf: - - type: string - - type: 'null' - title: Schedule Human Readable - description: Monitor schedule in plain text format. - user_key: - anyOf: - - type: string - - type: 'null' - title: User Key - description: Masked API key associated with this monitor. + description: Timestamp of when this status was set. type: object required: - - monitor_id - - reference_job_id - - reference_job_query - - enabled - title: MonitorListItemDto - SourceGroupApiResponseDto: + - status + title: DatasetStatusEntry + BillingFeatureWithUsage: properties: - slug: - type: string - title: Slug name: type: string title: Name - description: + description: Human-readable feature name. + code: + type: string + title: Code + description: Machine-readable feature identifier. + value_type: anyOf: - type: string - type: 'null' - title: Description + title: Value Type + description: Data type of the feature value. + value: + anyOf: + - {} + - type: 'null' + title: Value + description: Feature limit. Type depends on value_type. + current_usage: + anyOf: + - type: integer + - type: number + - type: 'null' + title: Current Usage + description: Current usage count for this feature. type: object required: - - slug - name - title: SourceGroupApiResponseDto - MonitorStatusEntryDto: + - code + title: PlanFeature + CsvSkippedRowDto: properties: - id: + row: type: integer - title: Id - description: Status entry identifier. - status: - type: string - title: Status - description: Type of lifecycle event. - created_at: + title: Row + description: 1-based row number in the CSV file including the header row. + reason: 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. + title: Reason + description: Human-readable explanation of why the row was skipped. type: object required: - - id - - status - - created_at - title: MonitorStatusEntry - ProjectResponseDto: + - row + - reason + title: SkippedRow + EnrichmentType: + type: string + enum: + - text + - number + - date + - option + - url + - company + title: EnrichmentType + description: 'Canonical enrichment types: text, number, date, option, url, company. + See Company enrichment docs for the company type data model.' + 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).' + WebhookDeliveryStatus: + type: string + enum: + - SUCCESS + - FAILED + title: WebhookDeliveryStatus + description: Webhook delivery outcome status. + CompanyAttributesDto: properties: - project_id: - type: string - format: uuid - title: Project Id - description: Project identifier. - name: - type: string - title: Name - description: Project name. - description: + alternative_names: anyOf: - - type: string + - items: + type: string + type: array - 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: Alternative Names + description: Alternative names, abbreviations, or aliases for the company. + domain: anyOf: - type: string - type: 'null' - title: Created At - description: Project creation timestamp. - updated_at: + title: Domain + description: Company website domain without protocol or trailing slash. + On create, the entity must have this or description set. + key_persons: anyOf: - - type: string + - items: + type: string + type: array - type: 'null' - title: Updated At - description: Timestamp of the last update. - sharing_info: + title: Key Persons + description: Names of key people associated with the company. + type: object + title: CompanyAttributes + BearerAuthResponseDto: + properties: + type: + type: string + const: bearer + title: Type + token: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: string - type: 'null' - description: Present when this project was shared with the authenticated - user. Omitted when the user owns the project. + title: Token + description: Masked bearer token. type: object required: - - project_id - - name - title: ProjectResponseDto - JobStep: + - type + title: BearerAuthResponse + BasicAuthResponseDto: properties: - status: - $ref: '#/components/schemas/PublicJobStatus' - order: - type: integer - title: Order - completed: - type: boolean - title: Completed - default: false + type: + type: string + const: basic + title: Type + username: + anyOf: + - type: string + - type: 'null' + title: Username + description: Basic auth username. + password: + anyOf: + - type: string + - type: 'null' + title: Password + description: Masked password. type: object required: - - status - - order - title: JobStep - ResourceItemRequestDto: + - type + title: BasicAuthResponse + ApiKeyAuthResponseDto: properties: - resource_type: - $ref: '#/components/schemas/ProjectResourceTypeEnum' - description: Type of resource to add. - resource_id: + type: type: string - format: uuid - title: Resource Id - description: ID of the resource to add. + const: api_key + title: Type + header: + anyOf: + - type: string + - type: 'null' + title: Header + description: HTTP header name for the API key. + value: + anyOf: + - type: string + - type: 'null' + title: Value + description: Masked API key value. type: object required: - - resource_type - - resource_id - title: ResourceItemDto - ResourceItemResponseDto: + - type + title: ApiKeyAuthResponse + CitationDto: 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: + type: + anyOf: + - type: string + - type: 'null' + title: Type + description: Source type of the citation, e.g. 'news'. + title: anyOf: - type: string - type: 'null' - title: Name - description: Resource display name. - created_at: + title: Title + description: Title of the source document. + link: 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 - BillingFeatureWithUsage: - properties: - name: - type: string - title: Name - description: Human-readable feature name. - code: - type: string - title: Code - description: Machine-readable feature identifier. - value_type: + format: uri + title: Link + description: URL to the source document. + published_date: anyOf: - type: string - type: 'null' - title: Value Type - description: Data type of the feature value. - value: + title: Published Date + description: Publication date of the source document. + type: object + title: Citation + EventTagsDto: + properties: + event_type: anyOf: - - {} + - type: string - type: 'null' - title: Value - description: Feature limit. Type depends on value_type. - current_usage: + title: Event Type + description: Taxonomy path describing what happened, e.g. 'deals.merger_acquisition'. + 'unclassifiable' when no path fits. + sector: anyOf: - - type: integer - - type: number + - type: string - type: 'null' - title: Current Usage - description: Current usage count for this feature. - type: object - required: - - name - - code - title: PlanFeature - 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. + title: Sector + description: Industry sector the event belongs to, e.g. 'banking'. 'other_sector' + when no sector fits. type: object - required: - - row - - reason - title: SkippedRow + title: EventTags ConnectedEntityDto: properties: entity_id: @@ -6393,181 +6568,6 @@ components: description: ISO 8601 timestamp when this citation was added. type: object title: MonitorCitation - EnrichmentType: - type: string - enum: - - text - - number - - date - - option - - url - - company - title: EnrichmentType - description: 'Canonical enrichment types: text, number, date, option, url, company. - See Company enrichment docs for the company type data model.' - EventTagsDto: - properties: - event_type: - anyOf: - - type: string - - type: 'null' - title: Event Type - description: Taxonomy path describing what happened, e.g. 'deals.merger_acquisition'. - 'unclassifiable' when no path fits. - sector: - anyOf: - - type: string - - type: 'null' - title: Sector - description: Industry sector the event belongs to, e.g. 'banking'. 'other_sector' - when no sector fits. - type: object - title: EventTags - CitationDto: - 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. - 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 - ApiKeyAuthResponseDto: - properties: - type: - type: string - const: api_key - title: Type - header: - anyOf: - - type: string - - type: 'null' - title: Header - description: HTTP header name for the API key. - value: - anyOf: - - type: string - - type: 'null' - title: Value - description: Masked API key value. - type: object - required: - - type - title: ApiKeyAuthResponse - BearerAuthResponseDto: - properties: - type: - type: string - const: bearer - title: Type - token: - anyOf: - - type: string - - type: 'null' - title: Token - description: Masked bearer token. - type: object - required: - - type - title: BearerAuthResponse - BasicAuthResponseDto: - properties: - type: - type: string - const: basic - title: Type - username: - anyOf: - - type: string - - type: 'null' - title: Username - description: Basic auth username. - password: - anyOf: - - type: string - - type: 'null' - title: Password - description: Masked password. - type: object - required: - - type - title: BasicAuthResponse - 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).' - WebhookDeliveryStatus: - type: string - enum: - - SUCCESS - - FAILED - title: WebhookDeliveryStatus - description: Webhook delivery outcome status. securitySchemes: ApiKeyAuth: type: apiKey From d9ecf11efb894896cff89b7651a20f54b87d9da5 Mon Sep 17 00:00:00 2001 From: docs-update-bot Date: Fri, 23 Oct 2026 08:44:42 +0000 Subject: [PATCH 2/2] Docs | Update CatchAll API docs for v1.10.3 Co-Authored-By: Claude Opus 5.5 --- .../api-reference/catch-all-api.yml | 2 +- web-search-api/get-started/changelog.mdx | 33 +++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/web-search-api/api-reference/catch-all-api.yml b/web-search-api/api-reference/catch-all-api.yml index 29af308..d166c14 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.10.2 + version: 1.10.3 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. diff --git a/web-search-api/get-started/changelog.mdx b/web-search-api/get-started/changelog.mdx index 6bbf0d9..c693515 100644 --- a/web-search-api/get-started/changelog.mdx +++ b/web-search-api/get-started/changelog.mdx @@ -5,6 +5,39 @@ description: Track updates, improvements, and fixes to the CatchAll API. rss: true --- + +## Model updates and more accurate deduplication + +A quality release with no request or response schema changes. Enrichment and +deduplication now run on updated models, and deduplication no longer merges +records that belong apart. Existing jobs and event monitors pick up these +changes automatically. + +### Updated models + +Entity matching, precision filtering, event tagging, deduplication, and event +monitor group summaries now use updated models, with equal or better result +quality. Existing jobs and event monitors that were created with the retired +models switch to the current ones the next time they run or continue, so you +don't need to re-create them. + +### More accurate deduplication + +- Records from different jobs or event monitors are no longer merged. +- Unrelated incidents are no longer merged into the same record, including + through chains of earlier merges. +- If a merge can't be verified, the records stay separate instead of being + merged or dropped. +- Processing errors during deduplication keep every record instead of dropping + events. + +### Fixes and improvements + +- Event monitor group results are no longer saved with records silently + missing. If new records can't be processed, the update fails instead of + dropping them. + + ## Search turn in job responses and broader article matching