> ## Documentation Index > Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create job > Submit a query to create a new processing job. ## OpenAPI ````yaml catch-all-api post /catchAll/submit openapi: 3.1.0 info: title: NewsCatcher CatchAll API version: 1.6.3 description: > CatchAll is a web search API that generates unique datasets that don't exist anywhere else on the web. Built on NewsCatcher's proprietary real-world event index, it delivers state-of-the-art recall—finding all relevant events, not just top results. ### Authentication All endpoints except /health and /version require `x-api-key` header. If the key is invalid or missing, the API returns the `403 Forbidden` error. ### Job workflow 1. (Optional) Get suggestions via /catchAll/initialize 2. Submit a query via /catchAll/submit with optional date ranges and custom validators/enrichments 3. Poll /catchAll/status/{job_id} until completed (10-15 minutes) 4. Retrieve results via /catchAll/pull/{job_id} ### Monitor workflow 1. Create successful job via /catchAll/submit 2. Create monitor via /catchAll/monitors/create with schedule 3. Retrieve aggregated results via /catchAll/monitors/pull/{monitor_id} ### Webhook workflow 1. Create a webhook via `POST /catchAll/webhooks` 2. Attach it to a job or monitor via `POST /catchAll/webhooks/{webhook_id}/resources`, or pass `webhook_ids` at job or monitor creation time 3. Receive HTTP notifications at the configured URL when each job completes ### Company search workflow 1. Create a dataset via `POST /catchAll/datasets/` or `POST /catchAll/datasets/upload` 2. Wait for the dataset `latest_status` to reach `ready` 3. Submit a job with `connected_dataset_ids` pointing to your dataset 4. Retrieve results — each record includes a `connected_entities` array with relevance scores per matched company ### Important notes **Dynamic schemas**: Response schemas are generated dynamically by LLMs. Field names in the `enrichment` object may vary and are not deterministic across jobs unless explicitly specified. contact: name: NewsCatcher url: https://newscatcherapi.com email: support@newscatcherapi.com servers: - url: https://catchall.newscatcherapi.com description: Production server security: - ApiKeyAuth: [] tags: - name: Jobs description: Operations to create, monitor, and retrieve job results. externalDocs: description: Learn about job lifecycle and status tracking url: >- https://www.newscatcherapi.com/docs/web-search-api/get-started/quickstart - name: Monitors description: Operations to create, operate and retrieve monitor results. externalDocs: description: >- Automate recurring queries with scheduled jobs and webhook notifications. url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/monitors - name: Webhooks description: > Operations to create and manage reusable webhook endpoints. A webhook is a named HTTP endpoint that receives a POST notification when a job or monitor completes. Create webhooks once at the organization level and attach them to any number of jobs or monitors via `webhook_ids`. Supports Slack, Microsoft Teams, and generic HTTP targets with configurable delivery modes, authentication, and headers. externalDocs: description: Learn about centralized webhooks and notification setup url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/webhooks - name: Entities description: > Operations to create, update, and delete company entities. Entities are the building blocks of Company Watchlist. Each entity represents a company (or person) you want to track. Add identifying information such as domain, alternative names, and key persons to improve matching quality. externalDocs: description: Learn about Company Watchlist and entities url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search - name: Datasets description: > Operations to create and manage datasets of entities. A dataset is a named collection of entities — think of it as a watchlist or portfolio. Connect a dataset to a job via `connected_dataset_ids` to activate Company Watchlist. Datasets can be reused across multiple jobs and monitors. externalDocs: description: Learn about datasets and Company Watchlist url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/company-search - name: Projects description: | Operations to create, organize, and manage projects. A project is a named container for jobs, monitors, and datasets. Group related resources by use case, team, or client, and share them with teammates. Resources can be assigned at creation time or post-hoc. externalDocs: description: Learn about projects and resource organization url: >- https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/projects - name: Meta description: Operations to check API health and version. externalDocs: description: Find out more about NewsCatcher CatchAll API url: https://www.newscatcherapi.com/docs/web-search-api/get-started/introduction paths: /catchAll/submit: post: tags: - Jobs summary: Create job description: Submit a query to create a new processing job. operationId: createJob requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequestDto' example: query: Series B funding rounds for SaaS startups context: Focus on funding amount and company name start_date: '2026-02-18T00:00:00Z' end_date: '2026-02-23T00:00:00Z' limit: 10 mode: base responses: '200': $ref: '#/components/responses/SubmitResponse' '400': $ref: '#/components/responses/BadRequestError' '403': $ref: '#/components/responses/ForbiddenError' '422': $ref: '#/components/responses/ValidationError' externalDocs: description: Detailed documentation for job creation url: >- https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/create-job components: schemas: SubmitRequestDto: type: object required: - query properties: query: $ref: '#/components/schemas/Query' context: $ref: '#/components/schemas/Context' limit: $ref: '#/components/schemas/Limit' start_date: $ref: '#/components/schemas/StartDate' end_date: $ref: '#/components/schemas/EndDate' validators: type: array items: $ref: '#/components/schemas/ValidatorSchema' description: > Custom validators for filtering web page clusters. If not provided, validators are generated automatically based on the query. The system may also inject validators during the `analyzing` stage — for example, converting a relative time qualifier into an explicit event-date gate. The returned `validators[]` in the job status shows the complete applied set, including any system-added ones. enrichments: type: array items: $ref: '#/components/schemas/EnrichmentSchema' description: > Custom enrichment fields for data extraction. If not provided, enrichments are generated automatically based on the query. mode: type: string enum: - lite - base default: base description: > Job processing mode. - `base`: Full pipeline with validation and enrichment. - `lite`: Lightweight extraction with faster processing. Returns titles and citations only. connected_dataset_ids: type: array items: type: string format: uuid description: > Dataset IDs to connect to the job. When provided, this enables Company Watchlist mode — the job returns only events relevant to companies in the connected datasets. To set the minimum relevance threshold, use `ed_score_min`. The dataset must have `latest_status: ready` before the job is submitted. Submitting with a non-existent or inaccessible dataset ID returns `400`. example: - ccabb755-afc2-4047-b84c-78d1f23d49b2 ed_score_min: type: integer minimum: 1 maximum: 10 default: 2 description: > The minimum relevance score a connected entity must reach for its record to be included in results. Only valid when `connected_dataset_ids` is set; otherwise ignored. Records where no connected entity meets the threshold are excluded entirely. example: 3 project_id: type: string format: uuid description: > Project to assign this job to. The job appears in the project's resource list immediately after submission. example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04 webhook_ids: type: array items: type: string format: uuid description: | IDs of webhooks to notify when the job completes. Maximum 5 per job. example: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 fetch_all_watchlist_news: type: boolean default: false description: > When true, retrieves all news for connected Company Watchlist entities without topic filtering. Requires connected_dataset_ids to be set. ed_association_type: allOf: - $ref: '#/components/schemas/EntityAssociationType' 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. Query: type: string description: > Plain text question describing what to find. The system analyzes your input to generate search queries, validators, and extractors. More specific queries produce more focused results. example: Series B funding rounds for SaaS startups Context: type: string description: | Additional context to focus on specific aspects of your query. example: Focus on funding amount and company name Limit: type: integer minimum: 10 description: > Maximum number of records to return. If not specified, defaults to your plan limit. Use [`POST /catchAll/continue`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/continue-job) to extend the limit after job completion without reprocessing. example: 10 StartDate: type: string format: date-time description: > Start date for web search (ISO 8601 format with UTC timezone). Defines the start of the search window by web page discovery date, not event date. Web pages discovered within this range may describe events from any time period. Must be within plan's allowed search depth. Default is 5 days before current date if not specified. example: '2026-01-30T00:00:00Z' EndDate: type: string format: date-time description: > End date for web search (ISO 8601 format with UTC timezone). Defines the end of the search window by web page discovery date, not event date. Web pages discovered within this range may describe events from any time period. Must be within plan's allowed search depth and after start_date. Default is current date if not specified. example: '2026-02-05T00:00:00Z' ValidatorSchema: type: object required: - name - description properties: name: type: string description: Validator field name (snake_case recommended). example: is_series_b_funding description: type: string description: What this validator checks for in the web page. example: true if the web page describes a Series B funding round type: type: string enum: - boolean default: boolean description: Validator type (currently only boolean supported). description: > Schema for a single validator that filters clusters of web pages. Validators are applied during the enriching stage to determine which clusters are relevant. EnrichmentSchema: type: object required: - name - description - type properties: name: type: string description: Enrichment field name (snake_case recommended). example: investee_company description: type: string description: What information this field extracts. example: Extract the name of the SaaS startup receiving the funding type: $ref: '#/components/schemas/EnrichmentType' description: > Schema for a single enrichment field that extracts structured data. Enrichments are applied during the enriching stage to extract information from validated clusters. EntityAssociationType: type: string enum: - mention - event_associated description: > How an entity relates to an event. - `event_associated`: The entity is a direct actor in the event (primary subject). - `mention`: The entity is merely referenced in passing. SubmitResponseDto: type: object required: - job_id properties: job_id: type: string format: uuid description: >- Unique identifier for the created job. Use this to check status and retrieve results. example: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c Error: type: object properties: detail: type: string description: Error message. example: Invalid API key ValidationErrorResponse: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationErrorDetail' EnrichmentType: type: string enum: - text - number - date - option - url - company description: > Canonical enrichment types supported by the system. - `text`: Free-form text strings (names, descriptions, summaries) - `number`: Numeric values (amounts, counts, percentages) - `date`: ISO format dates (YYYY-MM-DD) - `option`: Enum-like fixed values (status, category) - `url`: Web URLs - `company`: Structured company data. Returns `source_text`, `confidence`, and `metadata`. See [Company enrichment](https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/company-enrichment-dto) data model. ValidationErrorDetail: type: object properties: loc: type: array items: oneOf: - type: string - type: integer description: Location of the validation error msg: type: string description: Error message type: type: string description: Error type responses: SubmitResponse: description: Job created successfully content: application/json: schema: $ref: '#/components/schemas/SubmitResponseDto' example: job_id: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c BadRequestError: description: > Bad request - invalid parameters or constraint violations. Common causes: date ranges outside plan limits, invalid job state for continuation. content: application/json: schema: $ref: '#/components/schemas/Error' examples: date_validation: summary: Date outside plan limit value: detail: >- start_date must be >= 2025-02-05, your plan limited to lookback 365 days. invalid_continuation: summary: Invalid job continuation value: detail: >- New limit must be greater than the previous limit for this job. ForbiddenError: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication. ````