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.
              sort_order:
                type: string
                enum:
                - asc
                - desc
                description: Sort order applied to results.
              total_jobs:
                type: integer
                description: Total number of jobs for this monitor.
              jobs:
                type: array
                items:
                  $ref: '#/components/schemas/MonitorJobItem'
                description: Array of job executions for this monitor.
    UnauthorizedError:
      description: API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            detail: X-API-Key header is required for this endpoint
    CreateMonitorResponse:
      description: Monitor created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateMonitorResponseDto'
          example:
            monitor_id: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
            status: Monitor Created Successfully
    NotFoundError:
      description: Job/monitor not found or results not available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ForbiddenError:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MonitorStatusHistoryResponse:
      description: Monitor status history retrieved successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MonitorStatusHistoryResponseDto'
          example:
            success: true
            message: null
            monitor_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            total_statuses: 39
            statuses:
            - status: disable
              created_at: '2026-02-06T00:42:00Z'
              additional_information: null
            - status: dump
              created_at: '2026-02-05T12:04:00Z'
              additional_information:
                nb_existing_records: 408
                nb_final_records: 28
            - status: scheduled
              created_at: '2026-02-05T12:00:00Z'
              additional_information:
                job_id: c3d4e5f6-a7b8-9012-cdef-345678901234
                start_date: '2026-02-04T12:00:00'
                end_date: '2026-02-05T12:00:00'
            - status: created
              created_at: '2026-01-19T16:28:00Z'
              additional_information: null
    PullMonitorResponse:
      description: Monitor results retrieved successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PullMonitorResponseDto'
    DeleteMonitorResponse:
      description: Monitor deleted successfully (or already deleted).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeleteMonitorResponseDto'
          example:
            success: true
            message: Monitor deleted successfully.
            monitor_id: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
    ListMonitorsResponse:
      description: List of user monitors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListMonitorsResponseDto'
          example:
            total: 3
            page: 1
            page_size: 100
            total_pages: 1
            monitors:
            - monitor_id: 7f3a8b2c-1e4d-4a5b-9c8d-6e7f8a9b0c1d
              reference_job_id: 5f0c9087-85cb-4917-b3c7-e5a5eff73a0c
              reference_job_query: Series B funding rounds for SaaS startups
              enabled: true
              schedule: 0 12 * * *
              schedule_human_readable: Every day at 12 PM
              timezone: UTC
              created_at: '2026-02-24T14:00:00Z'
              webhook:
                url: https://example.com/webhook
                method: POST
              user_key: '***...a1b2'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
    UpdateMonitorResponse:
      description: Monitor updated successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateMonitorResponseDto'
          example:
            monitor_id: 3fec5b07-8786-46d7-9486-d43ff67eccd4
            status: Monitor updated Successfully
  parameters:
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      description: 'Page number to retrieve.

        '
    Ownership:
      name: ownership
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/OwnershipFilter'
    Search:
      name: search
      in: query
      required: false
      schema:
        type: string
      description: Filter results by text (case-insensitive substring match).
    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      description: 'Number of records per page.

        '
    ProjectIdQuery:
      name: project_id
      in: query
      required: false
      description: Filter results to resources belonging to this project.
      schema:
        type: string
        format: uuid
      example: 60a85db4-78ec-4b78-876a-bc7d9cdadd04
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-token
      description: "API Key to authenticate requests.\n\nTo access the API, include your API key in the `x-api-token` header. \nTo obtain your API key, complete the [form](https://www.newscatcherapi.com/book-a-demo) or contact us directly.\n"
externalDocs:
  description: Find out more about Local News API
  url: https://www.newscatcherapi.com/docs/local-news-api/get-started/introduction