Newscatcher Monitors API
Operations to create, operate and retrieve monitor results.
OpenAPI Specification
openapi: 3.0.3
info:
title: Local News AggregationCount Monitors 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: 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
paths:
/catchAll/monitors:
get:
tags:
- Monitors
summary: List monitors
description: Returns all monitors created by the authenticated user.
operationId: listMonitors
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/ListMonitorsResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/create:
post:
tags:
- Monitors
summary: Create monitor
description: Create a scheduled monitor based on a reference job.
operationId: createMonitor
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMonitorRequestDto'
example:
reference_job_id: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
schedule: every day at 12 PM
timezone: UTC
backfill: true
limit: 10
webhook_ids:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'200':
$ref: '#/components/responses/CreateMonitorResponse'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/pull/{monitor_id}:
get:
tags:
- Monitors
summary: Get monitor results
description: Retrieve aggregated results from all jobs executed by a monitor.
operationId: pullMonitorResults
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
responses:
'200':
$ref: '#/components/responses/PullMonitorResponse'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/{monitor_id}/jobs:
get:
tags:
- Monitors
summary: List monitor jobs
description: Return all jobs executed by a monitor.
operationId: listMonitorJobs
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
- name: sort
in: query
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: Sort by start_date (asc or desc).
responses:
'200':
$ref: '#/components/responses/ListMonitorJobsResponse'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/{monitor_id}/status:
get:
tags:
- Monitors
summary: Get monitor status history
description: 'Returns the full execution history of a monitor as a list of status entries, ordered from newest to oldest.
'
operationId: getMonitorStatusHistory
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
responses:
'200':
$ref: '#/components/responses/MonitorStatusHistoryResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/catchAll/monitors/{monitor_id}/enable:
post:
tags:
- Monitors
summary: Enable monitor
description: Resume scheduled job execution for a monitor.
operationId: enableMonitor
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/EnableMonitorRequestDto'
example:
backfill: true
responses:
'200':
description: Monitor enabled successfully
content:
application/json:
schema:
type: object
required:
- success
- message
- monitor_id
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable success message.
example: Monitor enabled successfully.
monitor_id:
type: string
format: uuid
description: ID of the enabled monitor.
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/{monitor_id}/disable:
post:
tags:
- Monitors
summary: Disable monitor
description: Stop scheduled job execution for a monitor.
operationId: disableMonitor
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
responses:
'200':
description: Monitor disabled successfully
content:
application/json:
schema:
type: object
required:
- success
- message
- monitor_id
properties:
success:
type: boolean
description: True if the operation succeeded; false otherwise.
example: true
message:
type: string
description: Human-readable success message.
example: Monitor disabled successfully.
monitor_id:
type: string
format: uuid
description: ID of the disabled monitor.
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
/catchAll/monitors/{monitor_id}:
patch:
tags:
- Monitors
summary: Update monitor
description: Update the webhook configuration for an existing monitor.
operationId: updateMonitor
externalDocs:
description: Learn about monitor configuration
url: https://www.newscatcherapi.com/docs/web-search-api/how-to/configure-monitors
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMonitorRequestDto'
example:
webhook_ids:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'200':
$ref: '#/components/responses/UpdateMonitorResponse'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'422':
$ref: '#/components/responses/ValidationError'
delete:
tags:
- Monitors
summary: Delete monitor
description: 'Soft-deletes a monitor. The monitor is flagged as deleted, stops
executing scheduled jobs immediately, and no longer appears in list
results.
Only the monitor owner can delete a monitor. Returns `404` if the
monitor is not found or does not belong to the authenticated user.
Deleting an already-deleted monitor returns `200`.
'
operationId: deleteMonitor
parameters:
- name: monitor_id
in: path
required: true
schema:
type: string
format: uuid
description: Monitor identifier.
responses:
'200':
$ref: '#/components/responses/DeleteMonitorResponse'
'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'
MonitorListItemDto:
type: object
required:
- monitor_id
- reference_job_id
- reference_job_query
- enabled
properties:
monitor_id:
type: string
format: uuid
description: Monitor identifier.
example: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
reference_job_id:
type: string
format: uuid
description: Job identifier used as a reference for this monitor.
example: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
reference_job_query:
type: string
description: Plain text query from the reference job.
example: Series B funding rounds for SaaS startups
enabled:
type: boolean
description: True if the monitor is currently active; false otherwise.
example: true
schedule:
type: string
description: Cron expression for monitor schedule.
example: 0 12 * * *
schedule_human_readable:
type: string
description: The monitor schedule in a plain text format.
example: Every 24 hours
timezone:
type: string
description: Timezone for schedule execution.
example: UTC
created_at:
type: string
format: date-time
description: The date when the monitor was created.
example: '2025-10-23T14:30:00Z'
webhook:
oneOf:
- $ref: '#/components/schemas/WebhookDto'
- type: 'null'
description: Webhook configuration for this monitor, or null if not set.
user_key:
type: string
description: Masked API key associated with this monitor.
example: '***...a1b2'
sharing_info:
allOf:
- $ref: '#/components/schemas/SharingInfo'
description: 'Present when this monitor was shared with the authenticated user. Omitted when the user owns the monitor.
'
CreateMonitorRequestDto:
type: object
required:
- reference_job_id
- schedule
properties:
reference_job_id:
type: string
format: uuid
description: 'Job ID to use as template for scheduled runs. Defines the query, validators, and enrichments used for each scheduled run.
If [`backfill`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/monitors/create-monitor#body-backfill) is true, the job''s `end_date` must be within the last 7 days.
'
schedule:
type: string
description: 'Monitor schedule in plain text format. Minimum frequency depends on your plan.
'
example: every day at 12 PM UTC
timezone:
type: string
description: "The IANA timezone identifier used as the fallback when the `schedule` string does not include an explicit timezone.\n\nIf the schedule includes a timezone abbreviation (for example, `\"every day at 9am EST\"`), the parsed timezone takes priority and this value is ignored. \n"
example: America/New_York
default: UTC
webhook_ids:
type: array
items:
type: string
format: uuid
description: 'IDs of centralized webhooks to notify on each run completion.
Passing IDs here is equivalent to calling
`POST /catchAll/webhooks/{webhook_id}/resources` for each ID after creation.
Maximum 5 per monitor.
'
example:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
limit:
type: integer
minimum: 10
description: 'Maximum number of records per monitor run. If not provided, defaults to the plan limit.
'
backfill:
type: boolean
default: true
description: "If true, fills the data gap between the reference job's `end_date` and the first scheduled run. The reference job's `end_date` must be within the last 7 days. \n\nIf false, no gap filling occurs and the first run uses the current cron window only — the reference job's age does not matter.\n"
project_id:
type: string
format: uuid
description: 'Project to assign this monitor to. The monitor appears in the project''s resource list after creation.
'
example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
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
MonitorCitation:
allOf:
- $ref: '#/components/schemas/Citation'
- type: object
required:
- id
- job_id
- added_on
properties:
id:
type: string
description: Unique identifier of the document in the search index.
example: 8760624448e9815f9fb4abd114c75e76
job_id:
type: string
format: uuid
description: Job ID that found this citation.
example: 6269aa54-c332-4fff-8a65-0d4e82a365e8
added_on:
type: string
format: date-time
description: The date when the citation was added to the record in ISO 8601 format with UTC timezone.
example: '2025-11-14T21:00:00Z'
description: 'Citation with monitor-specific metadata. Used in monitor results and webhook payloads.
Extends base citation with tracking information for job_id and timestamps.
'
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
PullMonitorResponseDto:
type: object
required:
- monitor_id
- reference_job
- status
properties:
monitor_id:
type: string
format: uuid
description: Unique identifier for the monitor.
example: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
cron_expression:
type: string
description: 'The cron expression for a monitor schedule parsed from the text schedule you provide.
Standard cron format (minute hour day month day-of-week).
'
example: 0 12 * * *
timezone:
type: string
description: Timezone used for schedule execution.
example: UTC
reference_job:
$ref: '#/components/schemas/ReferenceJob'
run_info:
type: object
description: Execution time range for this monitor.
properties:
first_run:
type: string
format: date-time
description: Timestamp of the first job execution.
example: '2025-10-23T12:00:00Z'
last_run:
type: string
format: date-time
description: Timestamp of the most recent job execution.
example: '2025-11-07T12:00:00Z'
records:
type: integer
default: 0
description: Total number of records collected across all monitor jobs.
example: 487
status:
type: string
description: Current monitor status or error message if monitor creation failed.
example: Done
all_records:
type: array
items:
$ref: '#/components/schemas/MonitorRecord'
description: 'Aggregated records from all jobs executed by this monitor. Each record includes structured data extracted from web sources with citations.
'
limit:
type:
- integer
- 'null'
description: Record limit applied to this monitor's jobs.
example: 100
ValidationErrorResponse:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationErrorDetail'
MonitorStatusEntry:
type: object
required:
- status
- created_at
properties:
status:
type: string
enum:
- created
- enable
- disable
- scheduled
- dump
description: "Type of lifecycle event.\n\n- `created`: Monitor was created.\n- `enable`: Monitor was enabled.\n- `disable`: Monitor was disabled.\n- `scheduled`: A job was triggered for execution.\n `additional_information` contains `job_id`, `start_date`,\n and `end_date`.\n- `dump`: Results were collected after a job completed.\n `additional_information` contains `nb_existing_records`,\n `nb_final_records`, and optionally `webhook`.\n"
created_at:
type: string
format: date-time
description: Timestamp of this event in ISO 8601 format with UTC timezone.
example: '2026-02-05T12:04:00Z'
additional_information:
type:
- object
- 'null'
description: "Event-specific metadata. `null` for `created`, `enable`, and `disable` events.\n\nFor `scheduled`:\n```json\n{\n \"job_id\": \"c3d4e5f6-a7b8-9012-cdef-345678901234\",\n \"start_date\": \"2026-02-04T12:00:00\",\n \"end_date\": \"2026-02-05T12:00:00\"\n}\n```\n\nFor `dump`:\n```json\n{\n \"nb_existing_records\": 408,\n \"nb_final_records\": 28,\n \"webhook\": {\n \"success\": true,\n \"status_code\": 200,\n \"error_message\": null\n }\n}\n```\nThe `webhook` key is only present if the monitor has a webhook configured.\n"
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
MonitorStatusHistoryResponseDto:
type: object
required:
- success
- monitor_id
- total_statuses
- statuses
properties:
success:
type: boolean
description: True if the request succeeded; false otherwise.
example: true
message:
type:
- string
- 'null'
description: Optional message. `null` on success.
monitor_id:
type:
- string
- 'null'
format: uuid
description: Monitor identifier. `null` on failure.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
total_statuses:
type:
- integer
- 'null'
description: Total number of status entries in the history.
example: 39
statuses:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/MonitorStatusEntry'
description: Full status history, ordered newest to oldest.
Error:
type: object
properties:
detail:
type: string
description: Error message.
example: Invalid API key
CreateMonitorResponseDto:
type: object
required:
- status
properties:
monitor_id:
type:
- string
- 'null'
format: uuid
description: Monitor ID if successful, null if error.
status:
type: string
description: Creation status or error message
example: Monitor Created Successfully
ListMonitorsResponseDto:
type: object
required:
- total
- page
- page_size
- total_pages
- monitors
properties:
total:
type: integer
description: Total number of monitors for this user.
example: 3
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of monitors per page.
example: 100
total_pages:
type: integer
description: Total number of pages available.
example: 1
monitors:
type: array
items:
$ref: '#/components/schemas/MonitorListItemDto'
description: Array of monitor summaries.
DeleteMonitorResponseDto:
type: object
required:
- success
- message
- monitor_id
properties:
success:
type: boolean
description: True if the delete operation succeeded; false otherwise.
example: true
message:
type:
- string
- 'null'
description: Human-readable result message.
example: Monitor deleted successfully.
monitor_id:
type:
- string
- 'null'
format: uuid
description: ID of the deleted monitor. `null` on failure.
example: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
UpdateMonitorRequestDto:
type: object
properties:
webhook_ids:
type: array
items:
type: string
format: uuid
description: "Updated list of centralized webhook IDs for this monitor. \n\nReplaces all existing webhook assignments. Pass an empty array `[]` to clear all assignments. Omit to leave existing assignments unchanged.\n"
example:
- a1b2c3d4-e5f6-7890-abcd-ef1234567890
limit:
type: integer
minimum: 10
description: Updated maximum number of records per monitor run.
MonitorRecord:
allOf:
- $ref: '#/components/schemas/BaseRecord'
- type: object
required:
- citations
properties:
citations:
type: array
items:
$ref: '#/components/schemas/MonitorCitation'
description: Source documents with monitor-specific metadata (job_id, added_on timestamps).
added_on:
type: string
format: date-time
description: The date when this record was first added to monitor results in ISO 8601 format with UTC timezone.
example: '2025-11-14T21:00:00Z'
updated_on:
type: string
format: date-time
description: The date when this record was last updated in monitor results in ISO 8601 format with UTC timezone.
example: '2025-11-14T21:00:00Z'
description: 'Record with monitor-specific metadata. Used in monitor results and webhook payloads.
Includes timestamps tracking when records were added and updated, and citations include job tracking.
'
UpdateMonitorResponseDto:
type: object
required:
- monitor_id
- status
properties:
monitor_id:
type: string
format: uuid
description: Monitor identifier.
example: 3fec5b07-8786-46d7-9486-d43ff67eccd4
status:
type: string
description: Confirmation message.
default: Monitor updated Successfully
example: Monitor updated Successfully
EnableMonitorRequestDto:
type: object
description: Optional request body for enabling a monitor.
properties:
backfill:
type: boolean
default: true
description: "If true, fills the data gap between the last job's `end_date` and the first scheduled run after enabling. The last job's `end_date` must be within the last 7 days. \n\nIf false, no gap filling occurs and the first run uses the current cron window only — the last job's age does not matter.\n"
MonitorJobItem:
type: object
required:
- job_id
- start_date
- end_date
properties:
job_id:
type: string
format: uuid
description: Unique identifier for this job execution.
start_date:
type: string
format: date-time
description: Start of the data collection time window for this job execution (based on monitor schedule) in ISO 8601 format with UTC timezone.
example: '2025-11-14T21:00:00Z'
end_date:
type: string
format: date-time
description: End of the data collection time window for this job execution (based on monitor schedule) in ISO 8601 format with UTC timezone.
example: '2025-11-15T00:00:00Z'
OwnershipFilter:
type: string
enum:
- all
- own
- shared
default: all
description: "Controls which resources are returned based on ownership.\n\n- `all`: Returns resources owned by the user and resources shared\n with them (default, backward compatible).\n- `own`: Returns only resources created by the authenticated user.\n- `shared`: Returns only resources shared with the user by others.\n"
WebhookDto:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Webhook endpoint URL.
method:
type: string
enum:
- POST
- PUT
default: POST
description: HTTP method to use.
headers:
type: object
additionalProperties:
type: string
description: HTTP headers to include in request.
params:
type: object
description: Query string parameters.
auth:
type: array
items:
type: string
minItems: 2
maxItems: 2
description: Basic auth credentials [username, password].
ReferenceJob:
type: object
properties:
query:
type: string
description: Plain text query from the reference job.
example: Series B funding rounds for SaaS startups
context:
type: string
description: Context provided with the reference job query.
example: Focus on funding amount and company name
responses:
ListMonitorJobsResponse:
description: List of monitor jobs
content:
application/json:
schema:
type: object
required:
- monitor_id
- sort_order
- total_jobs
- jobs
properties:
monitor_id:
type: string
format: uuid
description: Monitor identifier.
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newscatcher/refs/heads/main/openapi/newscatcher-monitors-api-openapi.yml