From 1b64615accbe237960f0b0fd84be7eb73f31478c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 Oct 2026 14:21:27 +0000 Subject: [PATCH 1/2] chore: sync FastAPI OAS snapshot 2026-10-22 --- .../api-reference/fastapi-openapi.yml | 5181 +++++++++-------- 1 file changed, 2600 insertions(+), 2581 deletions(-) diff --git a/web-search-api/api-reference/fastapi-openapi.yml b/web-search-api/api-reference/fastapi-openapi.yml index 8cff135..9c4f2f5 100644 --- a/web-search-api/api-reference/fastapi-openapi.yml +++ b/web-search-api/api-reference/fastapi-openapi.yml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: NewsCatcher CatchAll API - version: 1.10.0 + version: 1.10.3 contact: name: NewsCatcher url: https://newscatcherapi.com @@ -2706,15 +2706,6 @@ tags: description: Operations to check API health and version. components: schemas: - CheckQueryQualityRequestDto: - properties: - query: - type: string - title: Query - type: object - required: - - query - title: CheckQueryQualityRequestDto CheckQueryQualityResponseDto: properties: status: @@ -2765,199 +2756,74 @@ components: title: Detail type: object title: HTTPValidationError - CreateEntitiesBatchRequestDto: + CheckQueryQualityRequestDto: properties: - entities: - items: - $ref: '#/components/schemas/CreateEntityRequestDto' - type: array - title: Entities - description: Array of entities to create. + query: + type: string + title: Query type: object required: - - entities - title: CreateEntitiesBatchRequest - MonitorStatusHistoryResponseDto: + - query + title: CheckQueryQualityRequestDto + ContinueResponseDto: 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: + job_id: + type: string + format: uuid + title: Job Id + description: UUID of the continued job. + previous_limit: 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 - WebhookHistoryByResourceDto: - 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 - 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: - - resource_type - - resource_id - - total - - page - - page_size - - items - title: WebhookHistoryByResourceDto - ListSourceGroupsApiResponseDto: - properties: - source_groups: - items: - $ref: '#/components/schemas/SourceGroupApiResponseDto' - type: array - title: Source Groups - total: - type: integer - title: Total - page: - type: integer - title: Page - page_size: + title: Previous Limit + description: The limit before this continue request. + new_limit: type: integer - title: Page Size + title: New Limit + description: The new limit now in effect. + status: + type: string + title: Status + description: Always 'accepted' on success. + default: accepted type: object required: - - source_groups - - total - - page - - page_size - title: ListSourceGroupsApiResponseDto - ProjectListResponseDto: + - job_id + - new_limit + title: ContinueResponseDto + TestWebhookRequestDto: 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. + payload: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Payload + description: Custom payload to send in the test request. type: object - required: - - total - - page - - page_size - - total_pages - - projects - title: ProjectListResponseDto - Body_createDatasetFromCsv: + title: TestWebhookRequestDto + CsvUploadToExistingResponseDto: properties: - file: - type: string - format: binary - title: File - name: - type: string - title: Name - description: - type: string - title: Description - project_id: + dataset_id: type: string - title: Project Id - type: object - required: - - file - - name - title: Body_createDatasetFromCsv - 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: + format: uuid + title: Dataset Id + description: ID of the dataset that was updated. + entities_created: 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. + 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: - - total - - page - - page_size - - total_pages - - resources - title: ProjectResourceListResponseDto - GetWebhookResponseDto: + - dataset_id + - entities_created + - validation_report + title: UploadCsvToDatasetResponse + CreateProjectResponseDto: properties: success: type: boolean @@ -2967,858 +2833,277 @@ 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: Webhook details. + title: Project Id + description: Project identifier. + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: Name of the created project. type: object required: - success - message - title: GetWebhookResponseDto - SuggestInitializeResponseDto: - properties: - query: - type: string - title: Query - description: Echo of the query from the request. - context: - anyOf: - - type: string - - type: 'null' - title: Context - description: 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: + 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: + 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/EnrichmentSchema' + $ref: '#/components/schemas/ResourceResultResponseDto' 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: Results + description: Per-resource outcome, one entry per submitted resource. type: object required: - - query - title: InitializeResponseDto - Ownership: + - success + - message + title: AddResourceResponseDto + EntityType: 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. - CreateWebhookRequestDto: + - company + - person + title: EntityType + description: The type of entity. 'company' for organizations (default), 'person' + for individuals. + GetProjectResponseDto: properties: - name: - type: string - title: Name - description: Human-readable label for this webhook. - example: Layoffs Alert - url: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: 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'. + title: Message + description: Human-readable result message. project_id: anyOf: - type: string format: uuid - type: 'null' title: Project Id - description: Optional project ID to associate this webhook with immediately - upon creation. - 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 - EntityResponseDto: - properties: - id: - type: string - format: uuid - title: Id - description: Unique identifier of the entity. - entity_type: - type: string - title: Entity Type - description: The type of entity. - organization_id: - type: string - title: Organization Id - description: Organization that owns this entity. + description: Project identifier. name: - type: string - title: Name - description: Entity name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Free-text description. - external_entity_id: anyOf: - type: string - type: 'null' - title: External Entity Id - description: External identifier for this entity. Null when not set. - additional_attributes: - anyOf: - - $ref: '#/components/schemas/AdditionalAttributesDto' - - type: 'null' - description: Type-specific attributes. - status: - $ref: '#/components/schemas/EntityStatus' - description: Processing status of the entity. - created_by_user_id: + title: Name + description: Project name. + description: anyOf: - type: string - type: 'null' - title: Created By User Id - description: ID of the user who created this entity. + 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 - format: date-time - type: 'null' title: Created At - description: Timestamp of when the entity was created. + description: Project creation timestamp. updated_at: anyOf: - type: string - format: date-time - type: 'null' title: Updated At - description: Timestamp of when the entity was last updated. + 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: - - id - - entity_type - - organization_id - - name - - status - title: EntityResponse - DatasetListResponseDto: + - success + - message + title: GetProjectResponseDto + CreateMonitorRequestDto: 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 - DeleteMonitorResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the delete operation succeeded; false otherwise. - message: + reference_job_id: 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 - SubmitRequestDto: - properties: - query: + 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 - minLength: 1 - title: Query - description: Natural-language question. Keywords and search queries are - extracted automatically. - schema: + 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: Schema - description: 'Advanced: custom JSON schema string that overrides the default - extraction schema. Use POST /initialize to discover a suitable schema.' - context: + 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: Context - description: Additional context to sharpen the search scope (geography, - industry, time frame, etc.). + 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: Maximum number of validated records to collect. Minimum 10. - Defaults to the plan limit. Use POST /continue to raise the limit later. - start_date: + 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: anyOf: - type: string - format: date-time + format: uuid - 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: Project Id + description: Project to associate this monitor with. + type: object + required: + - reference_job_id + - schedule + title: CreateMonitorRequestDto + PullMonitorResponseDto: + properties: + monitor_id: + type: string + format: uuid + title: Monitor Id + description: Unique identifier for the monitor. + cron_expression: anyOf: - type: string - format: date-time - type: 'null' - title: End Date - description: Latest article date. Cannot be provided without start_date. - validators: + title: Cron Expression + description: Cron expression for the monitor schedule. + timezone: anyOf: - - items: - $ref: '#/components/schemas/ValidatorSchema' - type: array + - 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: Boolean classifiers. Only articles where every validator returns - true are counted in valid_records. Provide at least one item or omit entirely. + 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: - - items: - $ref: '#/components/schemas/EnrichmentSchema' - type: array + - $ref: '#/components/schemas/RunInfoDto' - 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: Execution time range for this monitor. + records: anyOf: - - $ref: '#/components/schemas/ProcessingMode' + - type: integer - 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: 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: - type: string - format: uuid + $ref: '#/components/schemas/MonitorRecordDto' type: array - type: 'null' - title: Connected Dataset Ids - description: IDs of datasets whose entities narrow the retrieval scope. - When provided, ed_score_min defaults to 2 if not specified. - ed_score_min: + title: All Records + description: Aggregated records from all jobs executed by this monitor. + limit: anyOf: - type: integer - maximum: 10.0 - minimum: 1.0 - - type: 'null' - title: Ed Score Min - description: Minimum entity-domain relevance score (1–10). Only relevant - when connected_dataset_ids is set. Defaults to 2. - ed_association_type: - anyOf: - - $ref: '#/components/schemas/EntityAssociationType' - type: 'null' - description: Filter events by entity association type. 'event_associated' - keeps only events where the entity is a direct actor. 'mention' keeps - only events where the entity is merely referenced. Only relevant when - connected_dataset_ids is set. - webhook_ids: + title: Limit + description: Record limit applied to this monitor's jobs. + connected_datasets: anyOf: - items: - type: string - format: uuid + $ref: '#/components/schemas/ConnectedDatasetDto' type: array - type: 'null' - title: Webhook Ids - description: Webhook IDs to notify when the job completes. Max 5 per job. - project_id: + title: Connected Datasets + description: Datasets used to narrow retrieval scope, each with id and name. + is_all_news_query: anyOf: - - type: string - format: uuid + - type: boolean - 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: + title: Is All News Query + description: True when the reference job was submitted as an all-news (watchlist-generic) + query. + sharing_info: anyOf: - - items: - type: string - type: array + - $ref: '#/components/schemas/SharingInfoDto' - 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. + description: Present when this monitor was shared with the authenticated + user. Omitted when the user owns the monitor. 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 - ListMonitorJobsResponseDto: + - monitor_id + - reference_job + - status + title: PullMonitorResponseDto + PullResponseDto: 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 - EntityStatus: - type: string - enum: - - pending - - enriching - - ready - - failed - title: EntityStatus - description: 'Processing status of an entity: pending → enriching → ready. Failed - entities may still be used but matching quality may be reduced.' - ListDatasetEntitiesRequestDto: - properties: - page: - type: integer - minimum: 1.0 - title: Page - description: The page number to retrieve. - default: 1 - page_size: - type: integer - maximum: 500.0 - minimum: 1.0 - title: Page Size - description: The number of entities per page. - default: 100 - search: - anyOf: - - type: string - - type: 'null' - title: Search - description: Filters entities by name using case-insensitive substring match. - status: - anyOf: - - $ref: '#/components/schemas/EntityStatus' - - type: 'null' - description: Filter entities by processing status. - entity_type: - anyOf: - - $ref: '#/components/schemas/EntityType' - - type: 'null' - description: Filter entities by type. - sort_by: - $ref: '#/components/schemas/EntitySortBy' - description: Field to sort results by. - default: created_at - sort_order: - $ref: '#/components/schemas/SortOrder' - description: Sort direction. - default: desc - type: object - title: ListDatasetEntitiesRequest - EnableMonitorResponseDto: - properties: - success: - type: boolean - 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 - CsvUploadToExistingResponseDto: - properties: - dataset_id: - type: string - format: uuid - title: Dataset Id - description: ID of the dataset that was updated. - entities_created: - type: integer - title: Entities Created - description: Number of new entities created from the CSV. - validation_report: - $ref: '#/components/schemas/CsvValidationReportDto' - description: Summary of CSV processing results. - type: object - required: - - dataset_id - - entities_created - - validation_report - title: UploadCsvToDatasetResponse - DatasetEntityListResponseDto: - properties: - entities: - items: - $ref: '#/components/schemas/EntitySummaryDto' - type: array - title: Entities - description: Array of entity summary objects for this page. - total: - type: integer - title: Total - description: Total number of entities in the dataset. - page: - type: integer - title: Page - description: Current page number. - page_size: - type: integer - title: Page Size - description: Number of entities per page. - type: object - required: - - entities - - total - - page - - page_size - title: DatasetEntityListResponse - 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: Job Id - description: ID of the deleted job. Null on failure. - type: object - required: - - success - - message - title: DeleteJobResponseDto - 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 - 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 - 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 - AssignWebhookResourceResponseDto: - 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 - UpdateProjectResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project identifier. - type: object - required: - - success - - message - title: UpdateProjectResponseDto - CsvUploadCreateResponseDto: - properties: - dataset_id: - type: string - format: uuid - title: Dataset Id - description: Unique identifier of the created dataset. - dataset_name: - type: string - title: Dataset Name - description: Name of the created dataset. - entities_created: - type: integer - title: Entities Created - description: Number of entities successfully created from the CSV. - validation_report: - $ref: '#/components/schemas/CsvValidationReportDto' - description: Summary of CSV processing results. - type: object - required: - - dataset_id - - dataset_name - - entities_created - - validation_report - title: CreateDatasetCsvResponse - CreateEntityRequestDto: - properties: - name: - type: string - minLength: 1 - title: Name - description: Entity name. Required and must be non-empty. - entity_type: - type: string - title: Entity Type - description: The type of entity. - default: company - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Free-text description for disambiguation. The entity must have - this or additional_attributes.company_attributes.domain set. - external_entity_id: - anyOf: - - type: string - maxLength: 255 - - type: 'null' - title: External Entity Id - description: Optional external identifier for this entity. Free-form string, - not enforced as unique. - additional_attributes: - anyOf: - - $ref: '#/components/schemas/AdditionalAttributesDto' - - type: 'null' - description: Type-specific attributes for the entity. - type: object - required: - - name - title: CreateEntityRequest - CreateMonitorResponseDto: - properties: - monitor_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Monitor Id - description: Monitor identifier. Null if creation failed. - status: - type: string - title: Status - description: Creation status or error message. - default: Monitor Created Successfully - type: object - title: CreateMonitorResponseDto - PullResponseDto: - properties: - job_id: + job_id: type: string format: uuid title: Job Id @@ -3855,6 +3140,9 @@ components: - 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 @@ -3950,255 +3238,275 @@ components: description: Datasets used to narrow retrieval scope, each with id and name. is_all_news_query: anyOf: - - type: boolean - - type: 'null' - title: Is All News Query - description: True when the query was submitted as an all-news (watchlist-generic) - query. - source_groups: - anyOf: - - items: - $ref: '#/components/schemas/SourceGroupRefDto' - type: array - - type: 'null' - title: Source Groups - description: Source groups attached to this job, each with slug, name, and - description. - sharing_info: - anyOf: - - $ref: '#/components/schemas/SharingInfoDto' - - type: 'null' - description: Present when the job was shared with the calling user (not - their own). - type: object - required: - - job_id - title: PullJobResponseDto - 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 - 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 - EntitySortBy: - type: string - enum: - - created_at - - name - - status - title: EntitySortBy - description: Fields available for sorting entity list results. - MappableResourceType: - type: string - enum: - - job - - monitor - - monitor_group - title: MappableResourceType - description: 'Resource types that can be assigned to a webhook: job, monitor, - or monitor_group.' - UpdateWebhookResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - webhook: - anyOf: - - $ref: '#/components/schemas/WebhookResponseDto' - - type: 'null' - description: Updated webhook details. - type: object - required: - - success - - message - title: UpdateWebhookResponseDto - DatasetStatus: - type: string - enum: - - pending - - enriching - - ready - - failed - title: DatasetStatus - description: 'Processing status of a dataset: pending → enriching → ready. Failed - indicates one or more entity enrichments failed.' - EntityType: - type: string - enum: - - company - - person - title: EntityType - description: The type of entity. 'company' for organizations (default), 'person' - for individuals. - UpdateDatasetRequestDto: - properties: - name: + - 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: - - type: string + - items: + $ref: '#/components/schemas/SourceGroupRefDto' + type: array - type: 'null' - title: Name - description: Updated dataset name. - description: + title: Source Groups + description: Source groups attached to this job, each with slug, name, and + description. + sharing_info: anyOf: - - type: string + - $ref: '#/components/schemas/SharingInfoDto' - type: 'null' - title: Description - description: Updated description. + description: Present when the job was shared with the calling user (not + their own). type: object - title: UpdateDatasetRequest - CreateProjectRequestDto: + required: + - job_id + title: PullJobResponseDto + SubmitRequestDto: properties: - name: + query: type: string - title: Name - description: Name for the project. - description: + minLength: 1 + title: Query + description: Natural-language question. Keywords and search queries are + extracted automatically. + schema: anyOf: - type: string - type: 'null' - title: Description - description: Optional description. - type: object - required: - - name - title: CreateProjectRequestDto - EnableMonitorRequestDto: - properties: - backfill: + 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: boolean + - type: string - type: 'null' - title: Backfill - description: If True, enforce lookback check on last job; if False, skip - date check. - default: true - type: object - title: EnableMonitorRequestDto - description: Optional body for POST /{monitor_id}/enable. - UpdateWebhookRequestDto: - properties: - name: + title: Context + description: Additional context to sharpen the search scope (geography, + industry, time frame, etc.). + limit: + anyOf: + - type: integer + minimum: 10.0 + - type: 'null' + title: Limit + description: Maximum number of validated records to collect. Minimum 10. + Defaults to the plan limit. Use POST /continue to raise the limit later. + start_date: anyOf: - type: string + format: date-time - type: 'null' - title: Name - description: Updated webhook name. - url: + 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: Url - description: Updated webhook endpoint URL. - type: + title: End Date + description: Latest article date. Cannot be provided without start_date. + validators: anyOf: - - $ref: '#/components/schemas/WebhookType' + - items: + $ref: '#/components/schemas/ValidatorSchema' + type: array - type: 'null' - description: Updated webhook target type. - delivery_mode: + 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: - - $ref: '#/components/schemas/DeliveryMode' + - items: + $ref: '#/components/schemas/EnrichmentSchema' + type: array - type: 'null' - description: Updated delivery mode. - method: + 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/HttpMethod' + - $ref: '#/components/schemas/ProcessingMode' - type: 'null' - description: Updated HTTP method. - headers: + description: Processing mode. 'base' runs the full pipeline with clustering + and enrichment. 'lite' is faster with no clustering. + default: base + connected_dataset_ids: anyOf: - - additionalProperties: + - items: type: string - type: object + format: uuid + type: array - type: 'null' - title: Headers - description: Updated HTTP headers. - params: + title: Connected Dataset Ids + description: IDs of datasets whose entities narrow the retrieval scope. + When provided, ed_score_min defaults to 2 if not specified. + ed_score_min: + anyOf: + - type: integer + maximum: 10.0 + minimum: 1.0 + - type: 'null' + title: Ed Score Min + description: Minimum entity-domain relevance score (1–10). Only relevant + when connected_dataset_ids is set. Defaults to 2. + ed_association_type: + anyOf: + - $ref: '#/components/schemas/EntityAssociationType' + - type: 'null' + description: Filter events by entity association type. 'event_associated' + keeps only events where the entity is a direct actor. 'mention' keeps + only events where the entity is merely referenced. Only relevant when + connected_dataset_ids is set. + webhook_ids: + anyOf: + - items: + type: string + format: uuid + type: array + - type: 'null' + title: Webhook Ids + description: Webhook IDs to notify when the job completes. Max 5 per job. + project_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Project Id + description: Project ID to associate this job with. + fetch_all_watchlist_news: + type: boolean + title: Fetch All Watchlist News + description: When true, retrieves all news for connected Company Watchlist + entities without topic filtering. Requires connected_dataset_ids to be + set. + default: false + source_groups: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Source Groups + description: Slugs of source groups to scope fetching to their domain allowlists. + Fetch available source groups via GET /catchAll/source-groups. Max 20 + per job. + type: object + required: + - 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: + properties: + dataset_id: + type: string + format: uuid + title: Dataset Id + description: Unique identifier of the created dataset. + dataset_name: + type: string + title: Dataset Name + description: Name of the created dataset. + entities_created: + type: integer + title: Entities Created + description: Number of entities successfully created from the CSV. + validation_report: + $ref: '#/components/schemas/CsvValidationReportDto' + description: Summary of CSV processing results. + type: object + required: + - dataset_id + - dataset_name + - entities_created + - validation_report + title: CreateDatasetCsvResponse + EntityResponseDto: + properties: + id: + type: string + format: uuid + title: Id + description: Unique identifier of the entity. + entity_type: + type: string + title: Entity Type + description: The type of entity. + organization_id: + type: string + title: Organization Id + description: Organization that owns this entity. + name: + type: string + title: Name + description: Entity name. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Free-text description. + external_entity_id: + anyOf: + - type: string + - type: 'null' + title: External Entity Id + description: External identifier for this entity. Null when not set. + additional_attributes: anyOf: - - additionalProperties: - type: string - type: object + - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - title: Params - description: Updated query string parameters. - auth: + description: Type-specific attributes. + status: + $ref: '#/components/schemas/EntityStatus' + description: Processing status of the entity. + created_by_user_id: 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: string - type: 'null' - title: Auth - description: 'Authentication forwarded with each delivery. Supported types: - ''bearer'' (token), ''api_key'' (header + value), ''basic'' (username - + password).' - formatter_config: + title: Created By User Id + description: ID of the user who created this entity. + created_at: anyOf: - - $ref: '#/components/schemas/FormatterConfigDto' + - type: string + format: date-time - type: 'null' - description: Updated custom formatter configuration. - is_active: + title: Created At + description: Timestamp of when the entity was created. + updated_at: anyOf: - - type: boolean + - type: string + format: date-time - type: 'null' - title: Is Active - description: Set to true to activate or false to deactivate. + title: Updated At + description: Timestamp of when the entity was last updated. type: object - title: UpdateWebhookRequestDto - RemoveResourceResponseDto: + required: + - id + - entity_type + - organization_id + - name + - status + title: EntityResponse + GetWebhookResponseDto: properties: success: type: boolean @@ -4208,33 +3516,70 @@ components: 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: RemoveResourceResponseDto - UpdateProjectRequestDto: + title: GetWebhookResponseDto + ProjectOverviewResponseDto: properties: - name: - anyOf: - - type: string - - type: 'null' - title: Name - description: New name for the project. - description: + project_id: + type: string + format: uuid + title: Project Id + description: Project identifier. + overview: + additionalProperties: + additionalProperties: + type: integer + type: object + type: object + title: Overview + description: Resource counts grouped by type. + type: object + required: + - project_id + - overview + title: ProjectOverviewResponseDto + 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: Description - description: New description for the project. + title: Monitor Id + description: ID of the enabled monitor. type: object - title: UpdateProjectRequestDto - ListWebhooksForResourceResponseDto: + 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 webhooks assigned to this resource. + description: Total number of datasets matching the filter criteria. page: type: integer title: Page @@ -4242,113 +3587,121 @@ components: page_size: type: integer title: Page Size - description: Number of webhooks per page. + 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: + 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. - webhooks: + resources: items: - $ref: '#/components/schemas/WebhookResponseDto' + $ref: '#/components/schemas/WebhookResourceMappingResponseDto' type: array - title: Webhooks - description: Array of webhook objects. + title: Resources + description: Array of resource mappings on this page. type: object required: - total - page - page_size - total_pages - - webhooks - title: ListWebhooksForResourceResponseDto - SubmitResponseDto: + - resources + title: ListWebhookResourcesResponseDto + CreateProjectRequestDto: properties: - job_id: + name: 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 - 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: + title: Name + description: Name for the project. + description: 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 + title: Description + description: Optional description. type: object - title: UpdateMonitorRequestDto - DatasetSortBy: - type: string - enum: + required: - name - - created_at - - status - title: DatasetSortBy - description: Fields available for sorting dataset list results. - StatusResponseDto: - properties: - job_id: - type: string - format: uuid - title: Job Id - description: UUID of the job. - example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - status: + title: CreateProjectRequestDto + UpdateProjectRequestDto: + properties: + name: anyOf: - - $ref: '#/components/schemas/PublicJobStatus' + - type: string - type: 'null' - description: 'Current pipeline stage. Poll until ''completed'' or ''failed''. - Recommended interval: 5 seconds.' - steps: + title: Name + description: New name for the project. + description: anyOf: - - items: - $ref: '#/components/schemas/JobStep' - type: array + - type: string - type: 'null' - title: Steps - description: Ordered pipeline stages with completion flags. Use to show - a progress bar to the user. + title: Description + description: New description for the project. + type: object + title: UpdateProjectRequestDto + DatasetStatusHistoryResponseDto: + properties: + dataset_id: + type: string + format: uuid + title: Dataset Id + description: Dataset identifier. + history: + items: + $ref: '#/components/schemas/DatasetStatusEntryDto' + type: array + title: History + description: Status change entries, ordered oldest to newest. type: object required: - - job_id - title: StatusResponseDto + - dataset_id + - history + title: DatasetStatusHistoryResponse DisableMonitorResponseDto: properties: success: @@ -4371,275 +3724,540 @@ components: - success - message title: DisableMonitorResponseDto - CreateEntityResponseDto: + Body_uploadCSVToDataset: properties: - id: - type: string - format: uuid - title: Id - description: Unique identifier of the created entity. - status: + file: type: string - title: Status - description: Initial status of the entity. Always pending immediately after - creation. - default: pending + format: binary + title: File type: object required: - - id - title: CreateEntityResponse - CreateDatasetRequestDto: + - 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: - type: string - minLength: 1 + anyOf: + - type: string + - type: 'null' title: Name - description: Name for the dataset. - description: + description: Updated webhook name. + url: anyOf: - type: string - type: 'null' - title: Description - description: Optional description. - entity_ids: + title: Url + description: Updated webhook endpoint URL. + type: anyOf: - - items: - type: string - format: uuid - type: array + - $ref: '#/components/schemas/WebhookType' - type: 'null' - title: Entity Ids - description: IDs of existing entities to include in the dataset. - project_id: + description: Updated webhook target type. + delivery_mode: anyOf: - - type: string - format: uuid + - $ref: '#/components/schemas/DeliveryMode' - type: 'null' - title: Project Id - description: Project to assign this dataset to. - type: object - required: - - name - title: CreateDatasetRequest - CreateMonitorRequestDto: - properties: - reference_job_id: - type: string - format: uuid - title: Reference Job Id - description: ID of a completed job whose query/validators/enrichments this - monitor should repeat. - example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - schedule: - type: string - title: Schedule - description: 'Natural-language schedule string converted to a cron expression. - Examples: ''every day at 9 AM'', ''every Monday at 6 PM EST''. An inline - timezone in the text overrides the timezone field.' - example: every day at 9 AM - timezone: + description: Updated delivery mode. + method: anyOf: - - type: string + - $ref: '#/components/schemas/HttpMethod' - 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: Updated HTTP method. + headers: anyOf: - - items: + - additionalProperties: type: string - format: uuid - type: array + type: object - type: 'null' - title: Webhook Ids - description: Webhook IDs to notify on each run completion. Max 5 per monitor. - limit: + title: Headers + description: Updated HTTP headers. + params: anyOf: - - type: integer - minimum: 10.0 + - additionalProperties: + type: string + type: object - type: 'null' - title: Limit - description: Max results per monitor run. Minimum 10. Validated against - plan limit. - example: 50 - backfill: + title: Params + description: Updated query string parameters. + auth: + anyOf: + - oneOf: + - $ref: '#/components/schemas/BearerAuthDto' + - $ref: '#/components/schemas/ApiKeyAuthDto' + - $ref: '#/components/schemas/BasicAuthDto' + discriminator: + propertyName: type + mapping: + api_key: '#/components/schemas/ApiKeyAuthDto' + basic: '#/components/schemas/BasicAuthDto' + bearer: '#/components/schemas/BearerAuthDto' + - type: 'null' + title: Auth + description: 'Authentication forwarded with each delivery. Supported types: + ''bearer'' (token), ''api_key'' (header + value), ''basic'' (username + + password).' + formatter_config: + anyOf: + - $ref: '#/components/schemas/FormatterConfigDto' + - type: 'null' + description: Updated custom formatter configuration. + is_active: + anyOf: + - type: boolean + - type: 'null' + title: Is Active + description: Set to true to activate or false to deactivate. + type: object + 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: + page: + type: integer + minimum: 1.0 + title: Page + description: The page number to retrieve. + default: 1 + page_size: + type: integer + maximum: 500.0 + minimum: 1.0 + title: Page Size + description: The number of entities per page. + default: 100 + search: + anyOf: + - type: string + - type: 'null' + title: Search + description: Filters entities by name using case-insensitive substring match. + status: anyOf: - - type: boolean + - $ref: '#/components/schemas/EntityStatus' - 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 + description: Filter entities by processing status. + entity_type: + anyOf: + - $ref: '#/components/schemas/EntityType' + - type: 'null' + description: Filter entities by type. + sort_by: + $ref: '#/components/schemas/EntitySortBy' + description: Field to sort results by. + default: created_at + sort_order: + $ref: '#/components/schemas/SortOrder' + description: Sort direction. + default: desc + type: object + title: ListDatasetEntitiesRequest + UpdateProjectResponseDto: + properties: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: + type: string + title: Message + description: Human-readable result message. project_id: anyOf: - type: string format: uuid - type: 'null' title: Project Id - description: Project to associate this monitor with. + description: Project identifier. type: object required: - - reference_job_id - - schedule - title: CreateMonitorRequestDto - UpdateEntityRequestDto: + - success + - message + title: UpdateProjectResponseDto + CreateEntityRequestDto: properties: name: - anyOf: - - type: string - - type: 'null' + type: string + minLength: 1 title: Name - description: Updated entity name. + description: Entity name. Required and must be non-empty. + entity_type: + type: string + title: Entity Type + description: The type of entity. + default: company description: anyOf: - type: string - type: 'null' title: Description - description: Updated description. + description: Free-text description for disambiguation. The entity must have + this or additional_attributes.company_attributes.domain set. external_entity_id: anyOf: - type: string maxLength: 255 - type: 'null' title: External Entity Id - description: Updated external identifier for this entity. + description: Optional external identifier for this entity. Free-form string, + not enforced as unique. additional_attributes: anyOf: - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - description: Updated type-specific attributes. + description: Type-specific attributes for the entity. type: object - title: UpdateEntityRequest - ContinueRequestDto: + required: + - name + title: CreateEntityRequest + ListMonitorJobsResponseDto: properties: - job_id: + monitor_id: type: string format: uuid - title: Job Id - description: Existing job to extend with a higher result limit. - new_limit: + 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: + 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: - - type: integer + - 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: New Limit - description: New limit, must be greater than the current limit. If null, - raises to the plan maximum. - example: 250 + 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: Optional project ID to associate this webhook with immediately + upon creation. type: object required: - - job_id - title: ContinueRequestDto + - name + - url + title: CreateWebhookRequestDto example: - job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - new_limit: 250 - DatasetStatusHistoryResponseDto: + delivery_mode: full + name: Layoffs Alert + type: slack + url: https://hooks.slack.com/services/T000/B000/xxxx + CreateEntityResponseDto: properties: - dataset_id: + id: type: string format: uuid - title: Dataset Id - description: Dataset identifier. - history: - items: - $ref: '#/components/schemas/DatasetStatusEntryDto' - type: array - title: History - description: Status change entries, ordered oldest to newest. + title: Id + description: Unique identifier of the created entity. + status: + type: string + title: Status + description: Initial status of the entity. Always pending immediately after + creation. + default: pending type: object required: - - dataset_id - - history - title: DatasetStatusHistoryResponse - Body_uploadCSVToDataset: + - id + title: CreateEntityResponse + SubmitResponseDto: properties: - file: + job_id: type: string - format: binary - title: File + 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: - - file - title: Body_uploadCSVToDataset - EntityListResponseDto: + - 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: - entities: - items: - $ref: '#/components/schemas/EntityResponseDto' - type: array - title: Entities - description: Array of entity objects for this page. + mode: + type: string + const: webhook + title: Mode + default: webhook + webhook_id: + type: string + format: uuid + title: Webhook Id total: type: integer title: Total - description: Total number of entities matching the filter criteria. page: type: integer title: Page - description: Current page number. page_size: type: integer title: Page Size - description: Number of entities per page. + items: + items: + $ref: '#/components/schemas/WebhookStatusItemDto' + type: array + title: Items type: object required: - - entities + - webhook_id - total - page - - page_size - title: EntityListResponse - DatasetEntityIdsRequestDto: + - page_size + - items + title: WebhookHistoryByWebhookDto + DeleteJobResponseDto: properties: - entity_ids: - items: - type: string + 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: array - title: Entity Ids - description: List of entity IDs to add or remove. + - type: 'null' + title: Job Id + description: ID of the deleted job. Null on failure. type: object required: - - entity_ids - title: DatasetEntityIdsRequest - UpdateMonitorResponseDto: + - 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: anyOf: - type: string format: uuid - type: 'null' title: Monitor Id - description: Monitor identifier. - status: + description: ID of the deleted monitor. Null on failure. + type: object + required: + - success + - message + title: DeleteMonitorResponseDto + SuggestInitializeRequestDto: + properties: + query: type: string - title: Status - description: Confirmation message. - default: Monitor updated Successfully + 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 - title: UpdateMonitorResponseDto - AddResourceResponseDto: + 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 overall operation succeeded. + description: True if the operation succeeded; false otherwise. 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. + description: Human-readable result message. + project_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Project Id + description: ID of the deleted project. + deleted_resources: + anyOf: + - additionalProperties: + type: integer + type: object + - type: 'null' + title: Deleted Resources + description: Count of deleted resources grouped by type (job, 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: AddResourceResponseDto + title: DeleteProjectResponseDto ListWebhooksResponseDto: properties: total: @@ -4672,136 +4290,48 @@ components: - total_pages - webhooks title: ListWebhooksResponseDto - ContinueResponseDto: - properties: - job_id: - type: string - format: uuid - title: Job Id - description: UUID of the continued job. - previous_limit: - anyOf: - - type: integer - - type: 'null' - title: Previous Limit - description: The limit before this continue request. - new_limit: - type: integer - title: New Limit - description: The new limit now in effect. - status: - type: string - title: Status - description: Always 'accepted' on success. - default: accepted - type: object - required: - - job_id - - new_limit - title: ContinueResponseDto - ProjectOverviewResponseDto: - properties: - project_id: - type: string - format: uuid - title: Project Id - description: Project identifier. - overview: - additionalProperties: - additionalProperties: - type: integer - type: object - type: object - title: Overview - description: Resource counts grouped by type. - type: object - required: - - project_id - - overview - title: ProjectOverviewResponseDto - DatasetResponseDto: + UpdateMonitorRequestDto: 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: 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: - anyOf: - - type: string - - type: 'null' - title: Latest Status - description: Most recent processing status of the dataset. - created_by_user_id: + 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: Optional list of centralized webhook IDs to assign to this + monitor. Empty list clears assignments. + limit: anyOf: - - $ref: '#/components/schemas/SharingInfoDto' + - type: integer - type: 'null' - description: Present when this dataset was shared with the authenticated - user. - created_at: + title: Limit + description: Optional max results per monitor run (min 10, validated against + plan) + schedule: anyOf: - type: string - format: date-time - type: 'null' - title: Created At - description: Timestamp of when the dataset was created. - updated_at: + 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 - format: date-time - type: 'null' - title: Updated At - description: Timestamp of when the dataset was last updated. + 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: - - id - - organization_id - - name - title: DatasetResponse - CreateWebhookResponseDto: + title: UpdateMonitorRequestDto + UpdateWebhookResponseDto: properties: success: type: boolean @@ -4815,101 +4345,97 @@ components: anyOf: - $ref: '#/components/schemas/WebhookResponseDto' - type: 'null' - description: Created webhook details. + description: Updated webhook details. type: object required: - success - message - title: CreateWebhookResponseDto - ListWebhookResourcesResponseDto: + title: UpdateWebhookResponseDto + ContinueRequestDto: + properties: + job_id: + type: string + format: uuid + title: Job Id + description: Existing job to extend with a higher result limit. + new_limit: + anyOf: + - type: integer + - type: 'null' + title: New Limit + description: New limit, must be greater than the current limit. If null, + raises to the plan maximum. + example: 250 + type: object + required: + - job_id + title: ContinueRequestDto + example: + job_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + new_limit: 250 + WebhookHistoryByResourceDto: 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 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: items: - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' + $ref: '#/components/schemas/WebhookStatusItemDto' type: array - title: Resources - description: Array of resource mappings on this page. + title: Items type: object required: + - resource_type + - resource_id - total - page - page_size - - total_pages - - resources - title: ListWebhookResourcesResponseDto - GetProjectResponseDto: + - items + title: WebhookHistoryByResourceDto + DatasetEntityListResponseDto: properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string - title: Message - description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project identifier. - name: - anyOf: - - type: string - - type: 'null' - title: Name - description: Project name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Project description. - resources_count: + entities: + items: + $ref: '#/components/schemas/EntitySummaryDto' + type: array + title: Entities + description: Array of entity summary objects for this page. + total: 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. + title: Total + description: Total number of entities in the dataset. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of entities per page. type: object required: - - success - - message - title: GetProjectResponseDto + - entities + - total + - page + - page_size + title: DatasetEntityListResponse ListMonitorsResponseDto: properties: total: @@ -4942,163 +4468,94 @@ components: - total_pages - monitors title: ListMonitorsResponseDto - TestWebhookRequestDto: - properties: - payload: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Payload - description: Custom payload to send in the test request. - type: object - title: TestWebhookRequestDto - ProjectResourceTypeEnum: - type: string - enum: - - job - - monitor - - dataset - - monitor_group - - webhook - title: ProjectResourceTypeEnum - description: Resource type for project association. - ProcessingMode: - type: string - enum: - - base - - lite - title: ProcessingMode - description: Job processing mode. 'base' runs the full pipeline with clustering - and enrichment. 'lite' is a faster mode that skips clustering. - DeleteProjectResponseDto: + AssignWebhookResourceResponseDto: properties: success: type: boolean title: Success description: True if the operation succeeded; false otherwise. message: - type: string - title: Message - description: Human-readable result message. - project_id: anyOf: - type: string - format: uuid - - type: 'null' - title: Project Id - description: ID of the deleted project. - deleted_resources: - anyOf: - - additionalProperties: - type: integer - type: object - type: 'null' - title: Deleted Resources - description: Count of deleted resources grouped by type (job, monitor, dataset, - monitor_group). Includes a 'webhook_unlinked' count for webhooks that - were detached from the project (not deleted) as part of this operation - — webhooks are never deleted when a project is deleted, since a webhook - may be attached to other resources independently of this project. - type: object - required: - - success - - message - title: DeleteProjectResponseDto - CreateProjectResponseDto: - properties: - success: - type: boolean - title: Success - description: True if the operation succeeded; false otherwise. - message: - type: string title: Message description: Human-readable result message. - project_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Project Id - description: Project identifier. - name: - anyOf: - - type: string - - type: 'null' - title: Name - description: Name of the created project. - type: object - required: - - success - - message - title: CreateProjectResponseDto - TestWebhookResponseDto: - properties: - success: + already_existed: 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: + title: Already Existed + description: True if the mapping already existed. + default: false + mapping: anyOf: - - {} + - $ref: '#/components/schemas/WebhookResourceMappingResponseDto' - type: 'null' - title: Response Body - description: Response body returned by the webhook endpoint. + description: Created or existing resource mapping. type: object required: - success - - message - title: TestWebhookResponseDto - SuggestInitializeRequestDto: + 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: - query: + entity_ids: + items: + type: string + format: uuid + type: array + title: Entity Ids + description: List of entity IDs to add or remove. + type: object + required: + - entity_ids + title: DatasetEntityIdsRequest + CreateDatasetRequestDto: + properties: + name: type: string - title: Query - description: Natural-language question to analyse. The API returns the validators - and enrichments it would auto-generate for this query. - example: Which airlines expanded their routes in Asia? - context: + minLength: 1 + title: Name + description: Name for the dataset. + description: 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: + title: Description + description: Optional description. + entity_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: + title: Entity Ids + description: IDs of existing entities to include in the dataset. + project_id: anyOf: - - type: boolean + - type: string + format: uuid - 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. + title: Project Id + description: Project to assign this dataset to. type: object required: - - query - title: InitializeRequestDto - example: - context: Focus on low-cost carriers. - query: Which airlines expanded their routes in Asia? + - name + title: CreateDatasetRequest AssignWebhookResourceRequestDto: properties: resource_type: @@ -5114,573 +4571,650 @@ components: - resource_type - resource_id title: AssignWebhookResourceRequestDto - SortOrder: + EntitySortBy: type: string enum: - - asc - - desc - title: SortOrder - description: Sort direction for list results. 'asc' for ascending (oldest first), - 'desc' for descending (newest first). - AddResourceRequestDto: + - created_at + - name + - status + title: EntitySortBy + description: Fields available for sorting entity list results. + SuggestInitializeResponseDto: properties: - resources: + 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/ResourceItemRequestDto' + $ref: '#/components/schemas/ValidatorSchema' type: array - title: Resources - description: Resources to assign to the project. - type: object - required: - - resources - title: AddResourceRequestDto - GetFeaturesResponse: - properties: - features: + title: Validators + description: Suggested validators for filtering relevant web pages. + enrichments: items: - $ref: '#/components/schemas/BillingFeatureWithUsage' + $ref: '#/components/schemas/EnrichmentSchema' type: array - title: Features - description: Plan features with current usage. - type: object - required: - - features - title: GetPlanLimitsResponseDto - IssueType: - type: string - enum: - - missing_event_type - - too_vague - - too_specific - - wrong_timeframe - - static_content - - article_request - - multiple_event_types - - too_short - - too_long - title: IssueType - description: Specific categories of query issues - QueryStatus: - type: string - enum: - - good - - needs_work - - critical - title: QueryStatus - description: Query quality assessment levels - Suggestion: - properties: - issue: - $ref: '#/components/schemas/IssueType' - message: - type: string - title: Message - description: Clear, specific guidance - example: + title: Enrichments + description: Suggested enrichment fields for data extraction. + date_modification_message: anyOf: - - type: string + - items: + type: string + type: array - type: 'null' - title: Example - description: Example of improved query + title: Date Modification Message + description: Messages explaining date adjustments due to plan limits. type: object required: - - issue - - message - title: Suggestion - description: Actionable recommendation for query improvement - ValidationError: + - query + title: InitializeResponseDto + EntityListResponseDto: properties: - loc: + entities: items: - anyOf: - - type: string - - type: integer + $ref: '#/components/schemas/EntityResponseDto' type: array - title: Location - msg: - type: string - title: Message - type: - type: string - title: Error Type + title: Entities + description: Array of entity objects for this page. + total: + type: integer + title: Total + description: Total number of entities matching the filter criteria. + page: + type: integer + title: Page + description: Current page number. + page_size: + type: integer + title: Page Size + description: Number of entities per page. type: object required: - - loc - - msg - - type - title: ValidationError - MonitorStatusEntryDto: + - entities + - total + - page + - page_size + title: EntityListResponse + EnableMonitorRequestDto: properties: - id: - type: integer - title: Id - description: Status entry identifier. - status: - type: string - title: Status - description: Type of lifecycle event. - created_at: - type: string - format: date-time - title: Created At - description: Timestamp of this event. - additional_information: + backfill: anyOf: - - {} + - type: boolean - type: 'null' - title: Additional Information - description: Event-specific metadata. Null for created, enable, and disable - events. + title: Backfill + description: If True, enforce lookback check on last job; if False, skip + date check. + default: true type: object - required: - - id - - status - - created_at - title: MonitorStatusEntry - WebhookStatusItemDto: + title: EnableMonitorRequestDto + description: Optional body for POST /{monitor_id}/enable. + DatasetResponseDto: properties: id: - type: integer - title: Id - webhook_id: type: string format: uuid - title: Webhook Id - resource_type: - $ref: '#/components/schemas/WebhookHistoryResourceType' - resource_id: + title: Id + description: Unique identifier of the dataset. + organization_id: type: string - format: uuid - title: Resource Id - additional_info: + title: Organization Id + description: Organization that owns this dataset. + name: + type: string + title: Name + description: Dataset name. + description: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Additional Info - status_code: + 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: integer + - type: number - 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: + 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: - type: string - type: 'null' - title: Error Message - warning_message: + title: Latest Status + description: Most recent processing status of the dataset. + created_by_user_id: anyOf: - type: string - type: 'null' - title: Warning Message + title: Created By User Id + description: ID of the user who created this dataset. + sharing_info: + anyOf: + - $ref: '#/components/schemas/SharingInfoDto' + - type: 'null' + description: Present when this dataset was shared with the authenticated + user. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: Timestamp of when the dataset was created. + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: Timestamp of when the dataset was last updated. type: object required: - id - - webhook_id - - resource_type - - resource_id - - attempt_number - - timestamp - - delivery_status - title: WebhookStatusItemDto - SourceGroupApiResponseDto: + - organization_id + - name + title: DatasetResponse + ListSourceGroupsApiResponseDto: properties: - slug: + source_groups: + items: + $ref: '#/components/schemas/SourceGroupApiResponseDto' + type: array + title: Source Groups + total: + type: integer + title: Total + page: + type: integer + title: Page + page_size: + type: integer + title: Page Size + type: object + required: + - source_groups + - total + - page + - page_size + title: ListSourceGroupsApiResponseDto + Body_createDatasetFromCsv: + properties: + file: type: string - title: Slug + format: binary + title: File name: type: string title: Name description: - anyOf: - - type: string - - type: 'null' + type: string title: Description + project_id: + type: string + title: Project Id type: object required: - - slug + - file - name - title: SourceGroupApiResponseDto - ProjectResponseDto: + title: Body_createDatasetFromCsv + MonitorStatusHistoryResponseDto: properties: - project_id: - type: string - format: uuid - title: Project Id - description: Project identifier. - name: - type: string - title: Name - description: Project name. - description: + success: + type: boolean + title: Success + description: True if the request succeeded; false otherwise. + message: anyOf: - type: string - type: 'null' - title: Description - description: Project description. - resources_count: - type: integer - title: Resources Count - description: Number of resources assigned to this project. - default: 0 - created_at: + title: Message + description: Optional message. Null on success. + monitor_id: anyOf: - type: string + format: uuid - type: 'null' - title: Created At - description: Project creation timestamp. - updated_at: + title: Monitor Id + description: Monitor identifier. Null on failure. + total_statuses: + anyOf: + - type: 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 + 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: anyOf: - type: string + format: uuid - type: 'null' - title: Updated At - description: Timestamp of the last update. - sharing_info: - anyOf: - - $ref: '#/components/schemas/SharingInfoDto' - - type: 'null' - description: Present when this project was shared with the authenticated - user. Omitted when the user owns the project. + title: Monitor Id + description: Monitor identifier. + status: + type: string + title: Status + description: Confirmation message. + default: Monitor updated Successfully type: object - required: - - project_id - - name - title: ProjectResponseDto - ResourceItemResponseDto: + title: UpdateMonitorResponseDto + UpdateDatasetRequestDto: properties: - resource_type: - type: string - title: Resource Type - description: Type of the resource. - resource_id: - type: string - format: uuid - title: Resource Id - description: Resource identifier. name: anyOf: - type: string - type: 'null' title: Name - description: Resource display name. - created_at: + description: Updated dataset name. + description: anyOf: - type: string - type: 'null' - title: Created At - description: Resource creation timestamp. - metadata: - additionalProperties: true - type: object - title: Metadata - description: Additional resource-specific metadata. + title: Description + description: 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. type: object required: - - resource_type - - resource_id - title: ProjectResourceDto - WebhookResponseDto: + - total + - page + - page_size + - total_pages + - webhooks + title: ListWebhooksForResourceResponseDto + UpdateEntityRequestDto: 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 - description: Webhook target type. - delivery_mode: - type: string - title: Delivery Mode - description: Delivery mode for webhook payloads. - method: - type: string - title: Method - description: HTTP method used for delivery. - headers: - additionalProperties: true - type: object - title: Headers - description: HTTP headers included in requests. - params: - additionalProperties: true - type: object - title: Params - description: Query string parameters. - auth: - anyOf: - - oneOf: - - $ref: '#/components/schemas/BearerAuthResponseDto' - - $ref: '#/components/schemas/ApiKeyAuthResponseDto' - - $ref: '#/components/schemas/BasicAuthResponseDto' - discriminator: - propertyName: type - mapping: - api_key: '#/components/schemas/ApiKeyAuthResponseDto' - basic: '#/components/schemas/BasicAuthResponseDto' - bearer: '#/components/schemas/BearerAuthResponseDto' - - type: 'null' - title: Auth - description: Authentication configuration for this webhook. Sensitive values - (token, API key value, password) are masked as '***'. Present with type - indicator when auth is configured; null when no auth is set. - formatter_config: - anyOf: - - $ref: '#/components/schemas/FormatterConfigDto' - - type: 'null' - description: Formatter configuration. - is_active: - type: boolean - title: Is Active - description: True if the webhook is active; false otherwise. - organization_id: anyOf: - type: string - type: 'null' - title: Organization Id - description: Organization that owns this webhook. - created_by_user_id: + title: Name + description: Updated entity name. + description: anyOf: - type: string - type: 'null' - title: Created By User Id - description: ID of the user who created this webhook. - created_at: + title: Description + description: Updated description. + external_entity_id: anyOf: - type: string + maxLength: 255 - type: 'null' - title: Created At - description: Timestamp of when the webhook was created. - updated_at: + title: External Entity Id + description: Updated external identifier for this entity. + additional_attributes: anyOf: - - type: string + - $ref: '#/components/schemas/AdditionalAttributesDto' - type: 'null' - title: Updated At - description: Timestamp of when the webhook was last updated. - type: object - required: - - id - - name - - url - - type - - delivery_mode - - method - - is_active - title: WebhookDto - EnrichmentSchema: - properties: - name: - type: string - title: Name - description: Machine-friendly field name (snake_case recommended). - example: company_name - description: - type: string - title: Description - description: What information to extract from each article. - example: The name of the company that is conducting the layoffs. - type: - $ref: '#/components/schemas/EnrichmentType' - description: 'Data type for this enrichment field. Supported: text, number, - date, option, url, company.' - example: company - type: object - required: - - name - - description - - type - title: EnrichmentSchema - description: A custom extraction field added to each validated article. - ValidatorSchema: - properties: - name: - type: string - title: Name - description: Machine-friendly field name (snake_case recommended). - example: is_about_layoffs - description: - type: string - title: Description - description: Natural-language criterion evaluated against each article. - Returns true if the article satisfies this criterion. - example: The article is specifically about job layoffs or workforce reductions. - type: - type: string - const: boolean - title: Type - description: Always 'boolean'. Only articles where all validators return - true count as valid_records. - default: boolean + description: Updated type-specific attributes. type: object - required: - - name - - description - title: ValidatorSchema - description: A boolean classifier applied to every candidate article. - ApiKeyAuthDto: + title: UpdateEntityRequest + ManageEntitiesResponseDto: properties: - type: - type: string - const: api_key - title: Type - description: Authentication type. - header: - type: string - title: Header - description: HTTP header name for the API key, e.g. 'X-API-Key'. - value: + dataset_id: type: string - title: Value - description: API key value. + 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: - - type - - header - - value - title: ApiKeyAuth - HttpMethod: - type: string - enum: - - GET - - POST - - PUT - - PATCH - - DELETE - title: HttpMethod - description: HTTP method used for webhook delivery. - FormatterConfigDto: + - dataset_id + - affected_count + title: ManageEntitiesResponse + CreateWebhookResponseDto: properties: - template: - type: string - title: Template - description: Liquid template string rendered at dispatch time. Maximum 10 - KB. - example: '{"event": "{{ event }}", "count": {{ records_count }}}' - content_type: + success: + type: boolean + title: Success + description: True if the operation succeeded; false otherwise. + message: 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: Message + description: Human-readable result message. + webhook: + anyOf: + - $ref: '#/components/schemas/WebhookResponseDto' + - type: 'null' + description: Created webhook details. type: object required: - - template - title: FormatterConfig - DeliveryMode: + - success + - message + title: CreateWebhookResponseDto + ProjectResourceTypeEnum: 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: + - job + - monitor + - dataset + - monitor_group + - webhook + title: ProjectResourceTypeEnum + description: Resource type for project association. + CreateMonitorResponseDto: properties: - type: - type: string - const: basic - title: Type - description: Authentication type. - username: + monitor_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Monitor Id + description: Monitor identifier. Null if creation failed. + status: type: string - title: Username - description: Basic auth username. - password: + title: Status + description: Creation status or error message. + default: Monitor Created Successfully + type: object + title: CreateMonitorResponseDto + StatusResponseDto: + properties: + job_id: type: string - title: Password - description: Basic auth password. + 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: - - type - - username - - password - title: BasicAuth - WebhookType: + - job_id + title: StatusResponseDto + EntityStatus: type: string enum: - - generic - - slack - - teams - - custom - title: WebhookType - description: Webhook target type. 'slack' and 'teams' send pre-formatted payloads; - 'generic' and 'custom' send the raw result payload. - BearerAuthDto: + - 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: - type: - type: string - const: bearer - title: Type - description: Authentication type. - token: - type: string - title: Token - description: Bearer token value sent in the Authorization header. + resources: + items: + $ref: '#/components/schemas/ResourceItemRequestDto' + type: array + title: Resources + description: Resources to assign to the project. type: object required: - - type - - token - title: BearerAuth - AdditionalAttributesDto: + - resources + title: AddResourceRequestDto + ResourceListResponseDto: properties: - company_attributes: + 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: + properties: + features: + items: + $ref: '#/components/schemas/BillingFeatureWithUsage' + type: array + title: Features + description: Plan features with current usage. + type: object + required: + - features + title: GetPlanLimitsResponseDto + IssueType: + type: string + enum: + - missing_event_type + - too_vague + - too_specific + - wrong_timeframe + - static_content + - article_request + - multiple_event_types + - too_short + - too_long + title: IssueType + description: Specific categories of query issues + Suggestion: + properties: + issue: + $ref: '#/components/schemas/IssueType' + message: + type: string + title: Message + description: Clear, specific guidance + example: anyOf: - - $ref: '#/components/schemas/CompanyAttributesDto' + - type: string - type: 'null' - description: Identifying attributes for a company entity. - additionalProperties: true + title: Example + description: Example of improved query type: object - title: AdditionalAttributes - EntityAssociationType: + required: + - issue + - message + title: Suggestion + description: Actionable recommendation for query improvement + QueryStatus: type: string enum: - - mention - - event_associated - title: EntityAssociationType - description: 'How an entity relates to an event: direct actor or merely mentioned.' - MonitorJobItemResponseDto: + - good + - needs_work + - critical + title: QueryStatus + description: Query quality assessment levels + ValidationError: properties: - job_id: + loc: + items: + anyOf: + - type: string + - type: integer + type: array + title: Location + msg: type: string - format: uuid - title: Job Id - description: Unique identifier for this job execution. - start_date: - anyOf: - - type: string - - type: 'null' - title: Start Date - description: Start of the data collection time window for this job execution. - end_date: - anyOf: - - type: string - - type: 'null' - title: End Date - description: End of the data collection time window for this job execution. + title: Message + type: + type: string + title: Error Type type: object required: - - job_id - title: MonitorJobItem + - loc + - msg + - type + title: ValidationError CsvValidationReportDto: properties: total_rows: @@ -5709,49 +5243,117 @@ components: - skipped_count - skipped_rows title: ValidationReport - EntitySummaryDto: + ResourceResultResponseDto: properties: - id: - type: string - format: uuid - title: Id - description: Unique identifier of the entity. - name: + resource_type: type: string - title: Name - description: Entity name. - entity_type: + title: Resource Type + description: Type of the resource. + resource_id: type: string - title: Entity Type - description: The type of entity. - status: + 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: Status - description: Processing status of the entity. - description: + 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: - type: string + format: date-time - type: 'null' - title: Description - description: Free-text description. - external_entity_id: + title: Shared At + shared_by_user_id: anyOf: - type: string - type: 'null' - title: External Entity Id - description: External identifier for this entity. Null when not set. - attributes: + title: Shared By User Id + permission: anyOf: - - $ref: '#/components/schemas/AdditionalAttributesDto' + - type: string - type: 'null' - description: Type-specific attributes. + title: Permission type: object - required: - - id - - name - - entity_type - - status - title: EntitySummary + title: SharingInfo + MonitorRecordDto: + properties: + record_id: + anyOf: + - type: string + - type: 'null' + title: Record Id + description: Unique cluster identifier for this record. + record_title: + anyOf: + - type: string + - type: 'null' + title: Record Title + description: Event or cluster title. + enrichment: + additionalProperties: true + type: object + title: Enrichment + description: Custom enrichment fields extracted for this record. Keys match + the enrichment names defined in the job. Values are job-specific. For + 'company' type enrichments, each value is a CompanyEnrichmentOutput object. + enrichment_confidence: + anyOf: + - additionalProperties: + type: number + type: object + - type: 'null' + title: Enrichment Confidence + description: Per-field confidence scores for enrichment values. Keys mirror + the enrichment dict; values are floats in [0, 1]. + citations: + anyOf: + - items: + $ref: '#/components/schemas/MonitorCitationDto' + type: array + - type: 'null' + title: Citations + description: Source articles included in this record, with job attribution. + connected_entities: + anyOf: + - items: + $ref: '#/components/schemas/ConnectedEntityDto' + type: array + - type: 'null' + title: Connected Entities + description: Entities from connected datasets that matched this record. + added_on: + anyOf: + - type: string + - type: 'null' + title: Added On + description: ISO 8601 timestamp when this record was first added. + updated_on: + anyOf: + - type: string + - type: 'null' + title: Updated On + description: ISO 8601 timestamp when this record was last updated. + type: object + title: MonitorRecord ConnectedDatasetDto: properties: id: @@ -5774,6 +5376,32 @@ components: - id - name title: ConnectedDataset + ValidatorSchema: + properties: + name: + type: string + title: Name + description: Machine-friendly field name (snake_case recommended). + example: is_about_layoffs + description: + type: string + title: Description + description: Natural-language criterion evaluated against each article. + Returns true if the article satisfies this criterion. + example: The article is specifically about job layoffs or workforce reductions. + type: + type: string + const: boolean + title: Type + description: Always 'boolean'. Only articles where all validators return + true count as valid_records. + default: boolean + type: object + required: + - name + - description + title: ValidatorSchema + description: A boolean classifier applied to every candidate article. RunInfoDto: properties: first_run: @@ -5790,27 +5418,86 @@ components: description: ISO 8601 timestamp of the most recent completed run. type: object title: RunInfo - SharingInfoDto: + EnrichmentSchema: properties: - shared_at: + name: + type: string + title: Name + description: Machine-friendly field name (snake_case recommended). + example: company_name + description: + type: string + title: Description + description: What information to extract from each article. + example: The name of the company that is conducting the layoffs. + type: + $ref: '#/components/schemas/EnrichmentType' + description: 'Data type for this enrichment field. Supported: text, number, + date, option, url, company.' + example: company + type: object + required: + - name + - description + - type + title: EnrichmentSchema + description: A custom extraction field added to each validated article. + ReferenceJob: + properties: + query: anyOf: - type: string - format: date-time - type: 'null' - title: Shared At - shared_by_user_id: + title: Query + description: Plain text query from the reference job. + context: anyOf: - type: string - type: 'null' - title: Shared By User Id - permission: + title: Context + description: Context provided with the reference job query. + source_groups: + anyOf: + - items: + $ref: '#/components/schemas/SourceGroupRefDto' + type: array + - type: 'null' + title: Source Groups + description: Source groups attached to the reference job, each with slug, + name, and description. + type: object + title: ReferenceJob + PublicJobStatus: + type: string + enum: + - submitted + - analyzing + - fetching + - clustering + - enriching + - completed + - failed + title: PublicJobStatus + description: 'Current job processing status. Jobs progress through stages: submitted + → analyzing → fetching → clustering → enriching → completed. Later turns repeat + fetching, clustering, and enriching.' + DateRangeDto: + properties: + start_date: anyOf: - type: string - type: 'null' - title: Permission + title: Start Date + description: Inclusive start of the article date range (ISO 8601). + end_date: + anyOf: + - type: string + - type: 'null' + title: End Date + description: Inclusive end of the article date range (ISO 8601). type: object - title: SharingInfo - MonitorRecordDto: + title: DateRange + ArticleRecordDto: properties: record_id: anyOf: @@ -5843,11 +5530,11 @@ components: citations: anyOf: - items: - $ref: '#/components/schemas/MonitorCitationDto' + $ref: '#/components/schemas/CitationDto' type: array - type: 'null' title: Citations - description: Source articles included in this record, with job attribution. + description: Source articles included in this record. connected_entities: anyOf: - items: @@ -5856,45 +5543,161 @@ components: - type: 'null' title: Connected Entities description: Entities from connected datasets that matched this record. - added_on: + Present only when entity datasets are used. + tags: anyOf: - - type: string + - $ref: '#/components/schemas/EventTagsDto' - type: 'null' - title: Added On - description: ISO 8601 timestamp when this record was first added. - updated_on: + 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 + title: Record + 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 + SourceGroupRefDto: + properties: + slug: + type: string + title: Slug + description: Source group slug. + name: + type: string + title: Name + description: Source group name. + description: anyOf: - type: string - type: 'null' - title: Updated On - description: ISO 8601 timestamp when this record was last updated. + title: Description + description: Source group description. type: object - title: MonitorRecord - ReferenceJob: + 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.' + AdditionalAttributesDto: properties: - query: + company_attributes: + anyOf: + - $ref: '#/components/schemas/CompanyAttributesDto' + - type: 'null' + description: Identifying attributes for a company entity. + additionalProperties: true + type: object + title: AdditionalAttributes + 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 + description: Webhook target type. + delivery_mode: + type: string + title: Delivery Mode + description: Delivery mode for webhook payloads. + method: + type: string + title: Method + description: HTTP method used for delivery. + headers: + additionalProperties: true + type: object + title: Headers + description: HTTP headers included in requests. + params: + additionalProperties: true + type: object + title: Params + description: Query string parameters. + auth: + anyOf: + - oneOf: + - $ref: '#/components/schemas/BearerAuthResponseDto' + - $ref: '#/components/schemas/ApiKeyAuthResponseDto' + - $ref: '#/components/schemas/BasicAuthResponseDto' + discriminator: + propertyName: type + mapping: + api_key: '#/components/schemas/ApiKeyAuthResponseDto' + basic: '#/components/schemas/BasicAuthResponseDto' + bearer: '#/components/schemas/BearerAuthResponseDto' + - type: 'null' + title: Auth + description: Authentication configuration for this webhook. Sensitive values + (token, API key value, password) are masked as '***'. Present with type + indicator when auth is configured; null when no auth is set. + formatter_config: + anyOf: + - $ref: '#/components/schemas/FormatterConfigDto' + - type: 'null' + description: Formatter configuration. + is_active: + type: boolean + title: Is Active + description: True if the webhook is active; false otherwise. + organization_id: anyOf: - type: string - type: 'null' - title: Query - description: Plain text query from the reference job. - context: + title: Organization Id + description: Organization that owns this webhook. + created_by_user_id: anyOf: - type: string - type: 'null' - title: Context - description: Context provided with the reference job query. - source_groups: + title: Created By User Id + description: ID of the user who created this webhook. + 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: Timestamp of when the webhook was created. + updated_at: + anyOf: + - type: string + - type: 'null' + title: Updated At + description: Timestamp of when the webhook was last updated. type: object - title: ReferenceJob + required: + - id + - name + - url + - type + - delivery_mode + - method + - is_active + title: WebhookDto WebhookResourceMappingResponseDto: properties: id: @@ -5929,113 +5732,136 @@ components: - resource_type - resource_id title: WebhookResourceMappingDto - DateRangeDto: + DatasetStatusEntryDto: properties: - start_date: + status: + type: string + title: Status + description: Dataset processing status. + additional_information: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Start Date - description: Inclusive start of the article date range (ISO 8601). - end_date: + title: Additional Information + description: Additional context about the status change. + created_at: anyOf: - type: string + format: date-time - type: 'null' - title: End Date - description: Inclusive end of the article date range (ISO 8601). + title: Created At + description: Timestamp of when this status was set. type: object - title: DateRange - ArticleRecordDto: - properties: - record_id: - anyOf: - - type: string - - type: 'null' - title: Record Id - description: Unique cluster identifier for this record. - record_title: - anyOf: - - type: string - - type: 'null' - title: Record Title - description: Event or cluster title. - enrichment: - additionalProperties: true - type: object - title: Enrichment - description: Custom enrichment fields extracted for this record. Keys match - the enrichment names defined in the job. Values are job-specific. For - 'company' type enrichments, each value is a CompanyEnrichmentOutput object. - enrichment_confidence: - anyOf: - - additionalProperties: - type: number - type: object - - type: 'null' - title: Enrichment Confidence - description: Per-field confidence scores for enrichment values. Keys mirror - the enrichment dict; values are floats in [0, 1]. - citations: - anyOf: - - items: - $ref: '#/components/schemas/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. + 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: + properties: + template: + type: string + title: Template + description: Liquid template string rendered at dispatch time. Maximum 10 + KB. + example: '{"event": "{{ event }}", "count": {{ records_count }}}' + content_type: + 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 - title: Record - PublicJobStatus: + required: + - template + title: FormatterConfig + BearerAuthDto: + 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. + type: object + required: + - type + - token + title: BearerAuth + ApiKeyAuthDto: + properties: + type: + type: string + const: api_key + title: Type + description: Authentication type. + header: + type: string + title: Header + description: HTTP header name for the API key, e.g. 'X-API-Key'. + value: + type: string + title: Value + description: API key value. + type: object + required: + - type + - header + - value + title: ApiKeyAuth + DeliveryMode: type: string enum: - - submitted - - analyzing - - fetching - - clustering - - enriching - - completed - - failed - title: PublicJobStatus - description: 'Current job processing status. Jobs progress through stages: submitted - → analyzing → fetching → clustering → enriching → completed. Poll /catchAll/status/{job_id} - every 30-60 seconds until completed (typically 10-15 minutes).' - SourceGroupRefDto: + - 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: - slug: + type: type: string - title: Slug - description: Source group slug. - name: + const: basic + title: Type + description: Authentication type. + username: type: string - title: Name - description: Source group name. - description: - anyOf: - - type: string - - type: 'null' - title: Description - description: Source group description. + title: Username + description: Basic auth username. + password: + type: string + title: Password + description: Basic auth password. type: object required: - - slug - - name - title: SourceGroupRef + - type + - username + - password + title: BasicAuth UserJobResponseDto: properties: job_id: @@ -6055,6 +5881,9 @@ components: 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 @@ -6077,77 +5906,127 @@ components: - status - user_key title: UserJob - JobStep: + MonitorJobItemResponseDto: properties: - status: - $ref: '#/components/schemas/PublicJobStatus' - order: - type: integer - title: Order - completed: - type: boolean - title: Completed - default: false + job_id: + type: string + format: uuid + title: Job Id + description: Unique identifier for this job execution. + start_date: + anyOf: + - type: string + - type: 'null' + title: Start Date + description: Start of the data collection time window for this job execution. + end_date: + anyOf: + - type: string + - type: 'null' + title: End Date + description: End of the data collection time window for this job execution. type: object required: - - status - - order - title: JobStep - DatasetStatusEntryDto: + - job_id + title: MonitorJobItem + WebhookStatusItemDto: properties: - status: + id: + type: integer + title: Id + webhook_id: type: string - title: Status - description: Dataset processing status. - additional_information: + format: uuid + title: Webhook Id + resource_type: + $ref: '#/components/schemas/WebhookHistoryResourceType' + resource_id: + type: string + format: uuid + title: Resource Id + additional_info: anyOf: - additionalProperties: true type: object - type: 'null' - title: Additional Information - description: Additional context about the status change. - created_at: + 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 - format: date-time - type: 'null' - title: Created At - description: Timestamp of when this status was set. + title: Error Message + warning_message: + anyOf: + - type: string + - type: 'null' + title: Warning Message type: object required: - - status - title: DatasetStatusEntry - ResourceResultResponseDto: + - id + - webhook_id + - resource_type + - resource_id + - attempt_number + - timestamp + - delivery_status + title: WebhookStatusItemDto + EntitySummaryDto: properties: - resource_type: - type: string - title: Resource Type - description: Type of the resource. - resource_id: + 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: + title: Id + description: Unique identifier of the entity. + name: 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: Name + description: Entity name. + entity_type: + type: string + title: Entity Type + description: The type of entity. + status: + type: string + title: Status + description: Processing status of the entity. + description: + anyOf: + - type: string + - type: 'null' + title: Description + description: Free-text description. + external_entity_id: + anyOf: + - type: string + - type: 'null' + title: External Entity Id + description: External identifier for this entity. Null when not set. + attributes: + anyOf: + - $ref: '#/components/schemas/AdditionalAttributesDto' + - type: 'null' + description: Type-specific attributes. type: object required: - - resource_type - - resource_id - - success - - message - title: ResourceResultDto + - id + - name + - entity_type + - status + title: EntitySummary MonitorListItemResponseDto: properties: monitor_id: @@ -6211,183 +6090,195 @@ components: - reference_job_query - enabled title: MonitorListItemDto - ResourceItemRequestDto: + SourceGroupApiResponseDto: properties: - resource_type: - $ref: '#/components/schemas/ProjectResourceTypeEnum' - description: Type of resource to add. - resource_id: + slug: type: string - format: uuid - title: Resource Id - description: ID of the resource to add. - type: object - required: - - resource_type - - resource_id - title: ResourceItemDto - BillingFeatureWithUsage: - properties: + title: Slug name: type: string title: Name - description: Human-readable feature name. - code: - type: string - title: Code - description: Machine-readable feature identifier. - value_type: + description: anyOf: - type: string - type: 'null' - title: Value Type - description: Data type of the feature value. - value: + title: Description + type: object + required: + - slug + - name + title: SourceGroupApiResponseDto + MonitorStatusEntryDto: + properties: + id: + type: integer + title: Id + description: Status entry identifier. + status: + type: string + title: Status + description: Type of lifecycle event. + created_at: + type: string + format: date-time + title: Created At + description: Timestamp of this event. + additional_information: anyOf: - {} - type: 'null' - title: 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. + title: Additional Information + description: Event-specific metadata. Null for created, enable, and disable + events. type: object required: - - name - - code - title: PlanFeature - WebhookDeliveryStatus: - type: string - enum: - - SUCCESS - - FAILED - title: WebhookDeliveryStatus - description: Webhook delivery outcome status. - WebhookHistoryResourceType: - type: string - enum: - - job - - monitor - - monitor_group - - test - title: WebhookHistoryResourceType - description: 'Resource types a webhook_status row can be recorded against. - - - A superset of MappableResourceType: real deliveries are always tied to an - - attachable resource (job/monitor/monitor_group), but a manual test delivery - - (POST /webhooks/{id}/test) isn''t tied to any real resource, so it is recorded - - against the synthetic `test` type instead. Kept separate from - - MappableResourceType so `test` can never be accepted where an attachable - - resource type is expected (e.g. assigning a webhook to a resource).' - BasicAuthResponseDto: + - id + - status + - created_at + title: MonitorStatusEntry + ProjectResponseDto: properties: - type: + project_id: type: string - const: basic - title: Type - username: + format: uuid + title: Project Id + description: Project identifier. + name: + type: string + title: Name + description: Project name. + description: anyOf: - type: string - type: 'null' - title: Username - description: Basic auth username. - password: + 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: Password - description: Masked password. + title: Created At + description: Project creation timestamp. + updated_at: + anyOf: + - type: string + - type: 'null' + title: Updated At + description: Timestamp of the last update. + sharing_info: + anyOf: + - $ref: '#/components/schemas/SharingInfoDto' + - type: 'null' + description: Present when this project was shared with the authenticated + user. Omitted when the user owns the project. type: object required: - - type - title: BasicAuthResponse - BearerAuthResponseDto: + - project_id + - name + title: ProjectResponseDto + JobStep: properties: - type: + status: + $ref: '#/components/schemas/PublicJobStatus' + order: + type: integer + title: Order + completed: + type: boolean + title: Completed + default: false + type: object + required: + - status + - order + title: JobStep + ResourceItemRequestDto: + properties: + resource_type: + $ref: '#/components/schemas/ProjectResourceTypeEnum' + description: Type of resource to add. + resource_id: type: string - const: bearer - title: Type - token: - anyOf: - - type: string - - type: 'null' - title: Token - description: Masked bearer token. + format: uuid + title: Resource Id + description: ID of the resource to add. type: object required: - - type - title: BearerAuthResponse - ApiKeyAuthResponseDto: + - resource_type + - resource_id + title: ResourceItemDto + ResourceItemResponseDto: properties: - type: + resource_type: type: string - const: api_key - title: Type - header: + 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: Header - description: HTTP header name for the API key. - value: + title: Name + description: Resource display name. + created_at: anyOf: - type: string - type: 'null' - title: Value - description: Masked API key value. + title: Created At + description: Resource creation timestamp. + metadata: + additionalProperties: true + type: object + title: Metadata + description: Additional resource-specific metadata. type: object required: - - type - title: ApiKeyAuthResponse - 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.' - CompanyAttributesDto: + - resource_type + - resource_id + title: ProjectResourceDto + BillingFeatureWithUsage: properties: - alternative_names: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Alternative Names - description: Alternative names, abbreviations, or aliases for the company. - domain: + name: + type: string + title: Name + description: Human-readable feature name. + code: + type: string + title: Code + description: Machine-readable feature identifier. + value_type: 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: + title: Value Type + description: Data type of the feature value. + value: anyOf: - - items: - type: string - type: array + - {} - type: 'null' - title: Key Persons - description: Names of key people associated with the company. + 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 - title: CompanyAttributes + required: + - name + - code + title: PlanFeature CsvSkippedRowDto: properties: row: @@ -6403,54 +6294,6 @@ components: - row - reason title: SkippedRow - MonitorCitationDto: - properties: - type: - anyOf: - - type: string - - type: 'null' - title: Type - description: Source type of the citation, e.g. 'news'. - title: - anyOf: - - type: string - - type: 'null' - title: Title - description: Title of the source document. - link: - anyOf: - - type: string - - type: 'null' - format: uri - title: Link - description: URL to the source document. - published_date: - anyOf: - - type: string - - type: 'null' - title: Published Date - description: Publication date of the source document. - id: - anyOf: - - type: string - - type: 'null' - title: Id - description: Citation identifier. - job_id: - anyOf: - - type: string - format: uuid - - type: 'null' - title: Job Id - description: Job identifier that found this citation. - added_on: - anyOf: - - type: string - - type: 'null' - title: Added On - description: ISO 8601 timestamp when this citation was added. - type: object - title: MonitorCitation ConnectedEntityDto: properties: entity_id: @@ -6502,6 +6345,66 @@ components: - name - type title: ConnectedEntity + MonitorCitationDto: + properties: + type: + anyOf: + - type: string + - type: 'null' + title: Type + description: Source type of the citation, e.g. 'news'. + title: + anyOf: + - type: string + - type: 'null' + title: Title + description: Title of the source document. + link: + anyOf: + - type: string + - type: 'null' + format: uri + title: Link + description: URL to the source document. + published_date: + anyOf: + - type: string + - type: 'null' + title: Published Date + description: Publication date of the source document. + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: Citation identifier. + job_id: + anyOf: + - type: string + format: uuid + - type: 'null' + title: Job Id + description: Job identifier that found this citation. + added_on: + anyOf: + - type: string + - type: 'null' + title: Added On + description: ISO 8601 timestamp when this citation was added. + type: object + title: MonitorCitation + 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: @@ -6549,6 +6452,122 @@ components: description: Publication date of the source document. type: object title: Citation + CompanyAttributesDto: + properties: + alternative_names: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Alternative Names + description: Alternative names, abbreviations, or aliases for the company. + domain: + anyOf: + - type: string + - type: 'null' + title: Domain + description: Company website domain without protocol or trailing slash. + On create, the entity must have this or description set. + key_persons: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Key Persons + description: Names of key people associated with the company. + type: object + title: CompanyAttributes + 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 8d3199d941279b15b3d5f2893cb14ddbf335231e Mon Sep 17 00:00:00 2001 From: docs-update-bot Date: Fri, 23 Oct 2026 08:26:01 +0000 Subject: [PATCH 2/2] Docs | Update CatchAll API docs for v1.10.2 Co-Authored-By: Claude Opus 5.5 --- .../api-reference/catch-all-api.yml | 28 +++++++++++- web-search-api/concepts/jobs.mdx | 27 +++++++++++ web-search-api/get-started/changelog.mdx | 45 +++++++++++++++++++ web-search-api/get-started/quickstart.mdx | 3 ++ 4 files changed, 102 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 d0d76da..29af308 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.0 + version: 1.10.2 description: | CatchAll is a web search API that generates unique datasets that don't exist anywhere else on the web. Built on NewsCatcher's proprietary real-world event index, it delivers state-of-the-art recall—finding all relevant events, not just top results. @@ -3744,6 +3744,8 @@ components: - `completed`: Job finished successfully, results ready. - `failed`: Job processing failed. + Later search turns repeat `fetching`, `clustering`, and `enriching`, so a job can return to `fetching` after `enriching`. + Poll `/catchAll/status/{job_id}` every 30-60 seconds until status is `completed` (typically 10-15 minutes). example: "fetching" @@ -3767,6 +3769,18 @@ components: default: false description: True if this step has finished processing; false otherwise. + JobIterationInfo: + type: object + properties: + turn: + type: integer + default: 1 + minimum: 1 + description: | + Current 1-indexed search turn. Jobs search in up to four turns, and a job that moves to a later turn repeats `fetching`, `clustering`, and `enriching`. Jobs that run without turns are reported as turn 1. + example: 1 + description: Job progress details for multi-turn search. + StatusResponseDto: type: object required: @@ -3781,6 +3795,10 @@ components: allOf: - $ref: "#/components/schemas/PublicJobStatus" description: Current job processing status. + job_info: + allOf: + - $ref: "#/components/schemas/JobIterationInfo" + description: Job progress details. `turn` is the current 1-indexed search turn. steps: type: array items: @@ -3845,6 +3863,10 @@ components: type: string description: Current processing status of the job. example: "completed" + job_info: + allOf: + - $ref: "#/components/schemas/JobIterationInfo" + description: Job progress details. `turn` is the current 1-indexed search turn. mode: type: string enum: ["lite", "base"] @@ -3897,6 +3919,10 @@ components: description: | Job status. example: "completed" + job_info: + allOf: + - $ref: "#/components/schemas/JobIterationInfo" + description: Job progress details. `turn` is the current 1-indexed search turn. error: type: [string, "null"] description: diff --git a/web-search-api/concepts/jobs.mdx b/web-search-api/concepts/jobs.mdx index 77e119d..79a0a55 100644 --- a/web-search-api/concepts/jobs.mdx +++ b/web-search-api/concepts/jobs.mdx @@ -330,6 +330,9 @@ while (true) { { "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c", "status": "completed", + "job_info": { + "turn": 1 + }, "steps": [ { "status": "submitted", @@ -390,6 +393,21 @@ as continued progress on the same job, and keep polling until the status is `completed` or `failed`. Records from earlier turns keep their IDs; articles found in later turns can be added to them as new citations. +To see which turn a job is on, read `job_info.turn` from the +[status](#get-job-status), [results](#get-job-results), or +[list user jobs](#list-user-jobs) response. Turns are numbered from 1. Jobs +that run without turns report `turn: 1`. + +```json +{ + "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c", + "status": "fetching", + "job_info": { + "turn": 2 + } +} +``` + ## Get job results [`GET /catchAll/pull/{job_id}`](/web-search-api/api-reference/jobs/get-job-results) @@ -492,6 +510,9 @@ while (true) { "other_investors" ], "status": "completed", + "job_info": { + "turn": 1 + }, "duration": "1m", "candidate_records": 4, "valid_records": 3, @@ -799,6 +820,9 @@ for (var job : jobs.getJobs()) { "query": "Series B funding rounds for SaaS startups", "created_at": "2026-02-24T13:57:56.267572", "status": "completed", + "job_info": { + "turn": 1 + }, "mode": "base" }, { @@ -806,6 +830,9 @@ for (var job : jobs.getJobs()) { "query": "Find corporate headquarters relocations in the US", "created_at": "2026-02-18T20:25:20.940731", "status": "completed", + "job_info": { + "turn": 1 + }, "mode": "lite" } ] diff --git a/web-search-api/get-started/changelog.mdx b/web-search-api/get-started/changelog.mdx index fbbb69f..6bbf0d9 100644 --- a/web-search-api/get-started/changelog.mdx +++ b/web-search-api/get-started/changelog.mdx @@ -5,6 +5,51 @@ description: Track updates, improvements, and fixes to the CatchAll API. rss: true --- + +## Search turn in job responses and broader article matching + +Job responses now report which search turn a job is on. Jobs also match against +full article content, and published records no longer include failed +extractions or records with unfinished quality checks. Existing jobs and event +monitors pick up these changes automatically. + +### Search turn in job responses + +`GET /catchAll/status/{job_id}`, `GET /catchAll/pull/{job_id}`, and +`GET /catchAll/jobs/user` now return a `job_info` object. Its `turn` field is +the current 1-indexed [search turn](/web-search-api/concepts/jobs#search-turns), +so you can tell when a job that goes back to `fetching` has moved to a later +turn. Jobs that run without turns report `turn: 1`. + +```json +{ + "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c", + "status": "fetching", + "job_info": { + "turn": 2 + } +} +``` + +### Broader article matching + +- Queries now match against full article content, not only titles and + summaries. +- Language-specific queries also match translated article content. +- Local News compatibility is restored. + +### Fixes and improvements + +- Published records no longer include failed extractions or records whose + correction or precision checks did not finish. This also applies to resumed + jobs and to results aggregated from a parent job. +- Better recovery from temporary provider failures. Failed validation and + extraction are retried, and resumed jobs reuse completed work instead of + repeating it. +- Records removed during deduplication no longer reappear when a job resumes. +- Faster matching of new articles to existing records in later search turns. + + ## Multi-turn search and per-company clustering diff --git a/web-search-api/get-started/quickstart.mdx b/web-search-api/get-started/quickstart.mdx index af854a6..089f881 100644 --- a/web-search-api/get-started/quickstart.mdx +++ b/web-search-api/get-started/quickstart.mdx @@ -250,6 +250,9 @@ Before you begin, make sure you meet these prerequisites: { "job_id": "af7a26d6-cf0b-458c-a6ed-4b6318c74da3", "status": "fetching", + "job_info": { + "turn": 1 + }, "steps": [ { "status": "submitted",