Newscatcher Jobs API
Operations to create, monitor, and retrieve job results.
OpenAPI Specification
openapi: 3.0.3
info:
title: Local News AggregationCount Jobs API
description: 'The Local News API provides access to local news articles with location-specific filtering capabilities.
## Standard endpoints
- `/search`: Search articles by keywords with simple location filtering ("City, State" format).
- `/latest_headlines`: Retrieve recent articles for specified locations and time periods.
- `/search_by`: Retrieve articles by URL, ID, or RSS GUID.
- `/sources`: List available news sources.
## Advanced endpoints
- `/search/advanced`: Search with structured GeoNames filtering.
- `/latest_headlines/advanced`: Latest headlines with structured GeoNames filtering.
## Features
- Multiple location detection methods including dedicated sources, proximity analysis, and AI extraction
- Natural language processing for sentiment analysis and entity recognition on original content and English translations
- Article clustering for topic analysis
- English translations for non-English content
'
termsOfService: https://newscatcherapi.com/terms-of-service
contact:
name: Maksym Sugonyaka
email: maksym@newscatcherapi.com
url: https://www.newscatcherapi.com/book-a-demo
version: 1.2.0
servers:
- url: https://local-news.newscatcherapi.com
description: Local News API 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
paths:
/catchAll/jobs/user:
get:
tags:
- Jobs
summary: List user jobs
description: Returns all jobs created by the authenticated user.
operationId: getUserJobs
externalDocs:
description: Learn about job management
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/list-user-jobs
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
- $ref: '#/components/parameters/Search'
- $ref: '#/components/parameters/Ownership'
- $ref: '#/components/parameters/ProjectIdQuery'
responses:
'200':
$ref: '#/components/responses/ListUserJobsResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
/catchAll/validate:
post:
tags:
- Jobs
summary: Validate query
description: 'Checks whether a query is well-formed and likely to produce good results before submitting a job.
Returns a quality assessment with a status level, identified issues, and actionable suggestions.
'
operationId: validateQuery
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateQueryRequestDto'
example:
query: Series B funding rounds for SaaS startups
responses:
'200':
$ref: '#/components/responses/ValidateQueryResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/initialize:
post:
tags:
- Jobs
summary: Initialize job
description: Get suggested validators, enrichments, and date ranges for a query.
operationId: initialize
externalDocs:
description: Learn about validator and enrichment suggestions
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/initialize-job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitializeRequestDto'
example:
query: Series B funding rounds for SaaS startups
context: Focus on funding amount and company name
responses:
'200':
$ref: '#/components/responses/InitializeResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/submit:
post:
tags:
- Jobs
summary: Create job
description: Submit a query to create a new processing job.
operationId: createJob
externalDocs:
description: Detailed documentation for job creation
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/create-job
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'
/catchAll/status/{job_id}:
get:
tags:
- Jobs
summary: Get job status
description: Retrieve the current processing status of a job.
operationId: getJobStatus
externalDocs:
description: Understanding job statuses and polling
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/get-job-status
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
$ref: '#/components/responses/StatusResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/pull/{job_id}:
get:
tags:
- Jobs
summary: Get job results
description: Retrieve the final results for a completed job.
operationId: getJobResults
externalDocs:
description: Working with job results and dynamic schemas
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/get-job-results
parameters:
- $ref: '#/components/parameters/JobId'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
$ref: '#/components/responses/PullJobResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/continue:
post:
tags:
- Jobs
summary: Continue job
description: Continue an existing job to process more records beyond the initial limit.
operationId: continueJob
externalDocs:
description: Learn about job continuation and limits
url: https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/continue-job
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContinueRequestDto'
example:
job_id: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
new_limit: 100
responses:
'200':
$ref: '#/components/responses/ContinueResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/jobs/{job_id}:
delete:
tags:
- Jobs
summary: Delete job
description: 'Soft-deletes a job. The job is flagged as deleted and no longer appears in list results. The underlying data is retained.
Only the job owner can delete a job. Returns `404` if the job is not found or does not belong to the authenticated user.
Deleting an already-deleted job returns `200`.
'
operationId: deleteJob
parameters:
- $ref: '#/components/parameters/JobId'
responses:
'200':
$ref: '#/components/responses/DeleteJobResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
Citation:
type: object
required:
- title
- link
- published_date
properties:
title:
type: string
description: The title of the source document.
example: 'Exclusive: VulnCheck raises $25M funding to help companies patch software bugs'
link:
type: string
format: uri
description: URL to the source document.
example: https://www.msn.com/en-us/money/other/exclusive-vulncheck-raises-25m-funding-to-help-companies-patch-software-bugs/ar-AA1WwdjW
published_date:
type: string
format: date-time
description: The publication date of the source document in ISO 8601 format (UTC timezone).
example: '2026-02-17T14:01:05Z'
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'
Suggestion:
type: object
description: Actionable recommendation for improving a query.
required:
- issue
- message
properties:
issue:
$ref: '#/components/schemas/IssueType'
description: The issue this suggestion addresses.
message:
type: string
description: Specific guidance for improving the query.
example: Add a target sector or geography to narrow the results.
example:
type: string
description: Revised query demonstrating the suggested improvement.
example: Series A fundraising for AI startups in healthcare
StatusResponseDto:
type: object
required:
- job_id
properties:
job_id:
type: string
format: uuid
description: Job identifier.
example: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
status:
allOf:
- $ref: '#/components/schemas/PublicJobStatus'
description: Current job processing status.
steps:
type: array
items:
$ref: '#/components/schemas/JobStep'
description: 'Detailed progress tracking for each processing stage. Steps progress sequentially from order 1 (submitted) through 5 (enriching), ending at order 6 (completed) or 7 (failed).
'
ListUserJobsResponseDto:
type: object
required:
- total
- page
- page_size
- total_pages
- jobs
properties:
total:
type: integer
description: Total number of jobs for this user.
example: 47
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of jobs per page.
example: 10
total_pages:
type: integer
description: Total number of pages available.
example: 5
jobs:
type: array
items:
$ref: '#/components/schemas/UserJob'
description: Array of user jobs on this page.
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'
BaseRecord:
type: object
required:
- record_id
- record_title
- enrichment
properties:
record_id:
type: string
description: Unique identifier for the record.
example: '6983973854314692457'
record_title:
type: string
description: Short title summarizing the record.
example: VulnCheck Raises $25M Series B Funding
enrichment:
type: object
description: "Structured data extracted from web pages. Schema is dynamically generated per job. Field names are chosen semantically to match the content.\n\n**Note:** The system always includes the `enrichment_confidence` field within the `enrichment` object, regardless of whether enrichments are generated or specified by you.\n\n For integration guidance, see [Dynamic schemas](https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/dynamic-schemas)\n"
properties:
enrichment_confidence:
type:
- string
- 'null'
enum:
- low
- medium
- high
- null
description: Overall confidence score for the enrichment extraction.
example: high
additionalProperties: {}
example:
enrichment_confidence: high
funding_amount: 25000000
funding_currency: USD
funding_date: '2026-02-17'
investee_company:
source_text: VulnCheck
confidence: 0.99
metadata:
name: VulnCheck
domain_url: vulncheck.com
domain_url_confidence: high
investor_company:
source_text: Sorenson Capital
confidence: 0.99
metadata:
name: Sorenson Capital
domain_url: null
domain_url_confidence: null
valuation: 25000000
other_investors: National Grid Partners, Ten Eleven Ventures, In-Q-Tel
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.
'
UserJob:
type: object
required:
- job_id
- query
- created_at
- status
properties:
job_id:
type: string
format: uuid
description: Job identifier.
example: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
query:
type: string
description: Plain text query for this job.
example: Series B funding rounds for SaaS startups
created_at:
type: string
format: date-time
description: Job creation timestamp in ISO 8601 format.
example: '2026-02-01T14:30:00Z'
status:
type: string
description: Current processing status of the job.
example: completed
mode:
type: string
enum:
- lite
- base
default: base
description: Processing mode used for this job.
example: base
sharing_info:
allOf:
- $ref: '#/components/schemas/SharingInfo'
description: 'Present when this job is shared with the authenticated user. Omitted when the user owns the job.
'
user_key:
type: string
description: Masked API key that created this job.
example: '***...a1b2'
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
Context:
type: string
description: 'Additional context to focus on specific aspects of your query.
'
example: Focus on funding amount and company name
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
ContinueResponseDto:
type: object
required:
- job_id
- new_limit
- status
properties:
job_id:
type: string
format: uuid
description: Job identifier for the continued job.
example: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
previous_limit:
type: integer
description: Previous record limit before continuation.
example: 10
new_limit:
type: integer
description: New record limit after continuation.
example: 100
status:
type: string
description: Confirmation that the continuation request was accepted.
default: accepted
example: accepted
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.
'
JobStep:
type: object
required:
- status
- order
- completed
properties:
status:
$ref: '#/components/schemas/PublicJobStatus'
order:
type: integer
description: Sequential position of this step in the pipeline (1-7).
minimum: 1
maximum: 7
example: 2
completed:
type: boolean
default: false
description: True if this step has finished processing; false otherwise.
ValidateQueryRequestDto:
type: object
required:
- query
properties:
query:
type: string
description: Plain text query to validate.
example: Series B funding rounds for SaaS startups
example:
query: Series B funding rounds for SaaS startups
ValidationErrorResponse:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationErrorDetail'
PullJobResponseDto:
type: object
required:
- job_id
properties:
job_id:
type: string
format: uuid
description: Job identifier.
query:
type: string
description: Original plain text query.
example: Series B funding rounds for SaaS startups
context:
type: string
description: Context provided with the query.
example: Focus on funding amount and company name
validators:
type: array
items:
type: object
description: Validators applied to filter results.
default: []
example: []
enrichments:
type: array
items:
type: object
description: Enrichment fields used for data extraction.
default: []
example: []
status:
type: string
description: 'Job status.
'
example: completed
error:
type:
- string
- 'null'
description: Error message if the job failed. Null for successful jobs.
limit:
type: integer
description: Record limit for this job. Reflects the value specified at submit time, or the plan default if no limit was provided.
example: 100
duration:
type: string
description: Total time taken to process the job.
example: 1m
candidate_records:
type: integer
description: Total number of distinct event clusters identified. Compare with `progress_validated` to estimate how many candidates remain unprocessed for job continuation.
example: 4
valid_records:
type: integer
description: Number of validated records extracted.
example: 3
progress_validated:
type:
- integer
- 'null'
description: 'Number of candidate clusters that have been validated during processing.
The system process data in batches. This field tracks how many `candidate_records` have been checked against validation criteria so far.
'
example: 4
date_range:
type: object
properties:
start_date:
type: string
format: date-time
example: '2026-02-17T00:00:00Z'
end_date:
type: string
format: date-time
example: '2026-02-24T00:00:00Z'
page:
type: integer
minimum: 1
default: 1
description: The current page number.
page_size:
type: integer
minimum: 1
default: 10
description: The number of records per page.
total_pages:
type: integer
minimum: 0
default: 0
description: The total number of pages available.
mode:
type: string
enum:
- lite
- base
default: base
description: Processing mode used for this job.
example: base
sharing_info:
oneOf:
- $ref: '#/components/schemas/SharingInfo'
- type: 'null'
description: 'Present when the job was shared with the authenticated user by another organization member. `null` when the user owns the job.
'
all_records:
type: array
items:
$ref: '#/components/schemas/Record'
description: Array of extracted records with structured data and citations.
SharingInfo:
type: object
description: 'Present on resources shared with the authenticated user by another
organization member. Omitted entirely on resources the user owns.
'
required:
- shared_at
- permission
- shared_by
properties:
shared_at:
type: string
format: date-time
description: When the resource was shared.
example: '2026-04-15T12:00:00Z'
permission:
type: string
enum:
- view
- edit
- manage
description: Permission level granted to the recipient.
example: view
shared_by:
type: string
description: 'Display name of the user who shared the resource (first + last
name). Falls back to email address, then user ID.
'
example: John Doe
InitializeRequestDto:
type: object
required:
- query
properties:
query:
$ref: '#/components/schemas/Query'
context:
$ref: '#/components/schemas/Context'
connected_dataset_ids:
type: array
items:
type: string
format: uuid
description: Optional list of watchlist dataset IDs connected to this job.
fetch_all_watchlist_news:
type: boolean
default: false
description: 'When true, returns generic news validators and enrichments suitable for
watchlist-based article collection instead of query-specific fields.
'
description: Request to get validator, enrichment, and date range suggestions for a query.
Record:
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
required:
- citations
properties:
citations:
type: array
items:
$ref: '#/components/schemas/Citation'
description: Source documents that were used to extract this record.
connected_entities:
type: array
items:
$ref: '#/components/schemas/ConnectedEntity'
description: 'Entities from the connected dataset that are relevant to this record.
Only present when the job was submitted with `connected_dataset_ids`.
'
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.
'
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.
'
Error:
type: object
properties:
detail:
type: string
description: Error message.
example: Invalid API key
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
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.
'
ConnectedEntity:
type: object
required:
- entity_id
- name
- type
- ed_score
- relation
description: 'A company entity matched to a record in a Company Watchlist job, with a relevance score and explanation.
Only entities with `ed_score` ≥ 1 appear in results. Entities scored 0 are filtered out before the response is returned. When `ed_score_min` is set at submission time, entities below that threshold are excluded.
'
properties:
entity_id:
type: string
format: uuid
description: Unique identifier of the matched entity.
example: e1f2a3b4-c5d6-7890-abcd-ef1234567890
name:
type: string
description: Name of the matched entity.
example: Tesla
ed_score:
type: integer
minimum: 1
maximum: 10
description: 'Relevance score indicating how directly the entity is associated with this event.
| Score | Meaning |
|-------|---------|
| 10 | Direct mention, critical event (merger, CEO change, major lawsuit) |
| 7–9 | Major impact (earnings, product launch, senior hire) |
| 4–6 | Routine update (minor product news, mid-level changes) |
| 1–3 | Indirect mention (listed with others, stock noise) |
'
example: 8
relation:
type: string
maxLength: 100
description: 'Short explanation (up to 100 characters) of why this entity is associated with the event.
'
example: Lucid Gravity is positioned as a direct competitor to the Tesla Model X.
association_type:
type: string
description: 'How the entity relates to the event: `event_associated` if the entity is a direct actor, `mention` if merely referenced.
'
example: event_associated
type:
type: string
description: 'The entity type.
'
example: company
company:
allOf:
- $ref: '#/components/schemas/CompanyAttributes'
description: "The stored attributes for this entity. Present only when
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-jobs-api-openapi.yml