openapi: 3.1.0
info:
  title: NewsCatcher CatchAll API
  version: 1.6.1
  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

externalDocs:
  description: Find out more about NewsCatcher CatchAll API
  url: https://www.newscatcherapi.com/docs/web-search-api/get-started/introduction

servers:
  - url: https://catchall.newscatcherapi.com
    description: Production server

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.

security:
  - ApiKeyAuth: []

paths:
  # ── Jobs ──────────────────────────────────────────────────────────────

  /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"

  # ── Monitors ──────────────────────────────────────────────────────────────

  /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"

  # ── Webhooks ──────────────────────────────────────────────────────────────

  /catchAll/webhooks:
    post:
      tags:
        - Webhooks
      summary: Create webhook
      description: |
        Creates a new webhook endpoint for the organization.
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWebhookRequestDto"
            example:
              name: "Layoffs Alert"
              url: "https://hooks.slack.com/services/T000/B000/xxx"
              type: "slack"
              delivery_mode: "full"
      responses:
        "201":
          $ref: "#/components/responses/CreateWebhookResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

    get:
      tags:
        - Webhooks
      summary: List webhooks
      description: Returns a paginated list of webhooks belonging to the organization.
      operationId: listWebhooks
      parameters:
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Number of webhooks per page.
        - $ref: "#/components/parameters/Search"
      responses:
        "200":
          $ref: "#/components/responses/ListWebhooksResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/webhooks/{webhook_id}:
    get:
      tags:
        - Webhooks
      summary: Get webhook
      description: Returns the full configuration of a single webhook by ID.
      operationId: getWebhook
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      responses:
        "200":
          $ref: "#/components/responses/GetWebhookResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    patch:
      tags:
        - Webhooks
      summary: Update webhook
      description: |
        Updates one or more fields of an existing webhook.
      operationId: updateWebhook
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWebhookRequestDto"
            example:
              name: "Layoffs Alert (EU)"
              is_active: false
      responses:
        "200":
          $ref: "#/components/responses/UpdateWebhookResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      tags:
        - Webhooks
      summary: Delete webhook
      description: |
        Permanently deletes a webhook and removes all resource assignments. 
        
        Assigned jobs and monitors no longer trigger delivery to this webhook. This operation cannot be undone.
      operationId: deleteWebhook
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      responses:
        "204":
          description: Webhook deleted successfully. No response body.
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/webhooks/{webhook_id}/test:
    post:
      tags:
        - Webhooks
      summary: Test webhook delivery
      description: |
        Sends a test HTTP request to the webhook URL using the webhook's configured method, headers, and auth. Returns the response from the target endpoint.

        Use this to verify URL reachability and authentication before attaching the webhook to a live job or monitor.
      operationId: testWebhook
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestWebhookRequestDto"
            example:
              payload:
                test: true
                message: "CatchAll webhook test"
      responses:
        "200":
          $ref: "#/components/responses/TestWebhookResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/webhooks/{webhook_id}/resources:
    post:
      tags:
        - Webhooks
      summary: Assign resource to webhook
      description: |
        Attaches a job, monitor, or monitor group to the webhook. When the
        resource completes, the webhook receives a delivery.

        A single webhook can be assigned to multiple resources. Each resource
        can have up to 5 webhooks assigned.
      operationId: assignWebhookResource
      parameters:
        - $ref: "#/components/parameters/WebhookId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssignWebhookResourceRequestDto"
            example:
              resource_type: "monitor"
              resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
      responses:
        "200":
          $ref: "#/components/responses/AssignWebhookResourceResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    get:
      tags:
        - Webhooks
      summary: List webhook resources
      description: |
        Returns a paginated list of resources currently assigned to this webhook.
      operationId: listWebhookResources
      parameters:
        - $ref: "#/components/parameters/WebhookId"
        - name: resource_type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/MappableResourceType"
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Number of assignments per page.
      responses:
        "200":
          $ref: "#/components/responses/ListWebhookResourcesResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/webhooks/{webhook_id}/resources/{resource_type}/{resource_id}:
    delete:
      tags:
        - Webhooks
      summary: Remove resource from webhook
      description: |
        Detaches a resource from this webhook. Completions of the resource no longer trigger delivery to this webhook.

        The webhook and the resource itself are not deleted.
      operationId: removeWebhookResource
      parameters:
        - $ref: "#/components/parameters/WebhookId"
        - $ref: "#/components/parameters/WebhookResourceType"
        - $ref: "#/components/parameters/WebhookResourceId"
      responses:
        "204":
          description: Resource removed from webhook. No response body.
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/resources/{resource_type}/{resource_id}/webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks for resource
      description: |
        Returns all webhooks currently assigned to the given resource.
      operationId: listWebhooksForResource
      parameters:
        - $ref: "#/components/parameters/WebhookResourceType"
        - $ref: "#/components/parameters/WebhookResourceId"
        - name: is_active
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by active status. Omit to return webhooks regardless of status.
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Number of webhooks per page.
      responses:
        "200":
          $ref: "#/components/responses/ListResourceWebhooksResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/webhook-history:
    get:
      tags:
        - Webhooks
      summary: Get delivery history
      description: |
        Returns a paginated delivery log for a given resource, ordered by timestamp descending. 
        
        Each record shows the webhook dispatched, the HTTP status code returned, delivery outcome, and any error or warning messages. Use this to debug failed deliveries or audit dispatch activity.
      operationId: getWebhookDeliveryHistory
      parameters:
        - name: resource_type
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/MappableResourceType"
          description: Type of the resource to retrieve delivery history for.
        - name: resource_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: Identifier of the resource to retrieve delivery history for.
          example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 500
          description: Number of records per page.
      responses:
        "200":
          $ref: "#/components/responses/DeliveryHistoryResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  # ── Entities ──────────────────────────────────────────────────────────────

  /catchAll/entities:
    get:
      tags:
        - Entities
      summary: List entities
      description: |
        Returns a paginated list of entities belonging to the authenticated organization. Supports filtering by status and entity type, and sorting by name, status, or creation date.
      operationId: listEntities
      parameters:
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Number of entities per page.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description:
            Filter entities by name (case-insensitive substring match).
          example: NewsCatcher
        - name: status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/EntityStatus"
        - name: entity_type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/EntityType"
        - name: sort_by
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/EntitySortBy"
        - name: sort_order
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SortOrder"
      responses:
        "200":
          $ref: "#/components/responses/EntityListResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"

    post:
      tags:
        - Entities
      summary: Create entity
      description: |
        Creates a new company entity and begins background enrichment.

        The entity status starts as `pending` and transitions to `ready` once
        enrichment completes. Provide as much identifying information as
        possible — `domain` is the highest-signal field because it is
        unambiguous.
      operationId: createEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntityRequest"
            example:
              name: NewsCatcher
              entity_type: company
              description: AI-powered news data provider
              additional_attributes:
                company_attributes:
                  domain: newscatcherapi.com
                  alternative_names:
                    - NC
                    - NewsCatcher API
                  key_persons:
                    - Artem Bugara
                    - Maksym Sugonyaka
      responses:
        "200":
          $ref: "#/components/responses/CreateEntityResponse"
        "400":
          $ref: "#/components/responses/EntityBadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"

  /catchAll/entities/batch:
    post:
      tags:
        - Entities
      summary: Create entities in batch
      description: |
        Creates multiple entities in a single request. Each entity is processed independently — a failure in one does not affect others.

        Returns an array of `{id, status}` objects in the same order as the input array.
      operationId: createEntitiesBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateEntitiesBatchRequest"
            example:
              entities:
                - name: OpenAI
                  entity_type: company
                  description: Artificial intelligence research company
                  additional_attributes:
                    company_attributes:
                      domain: openai.com
                      alternative_names:
                        - Open AI
                      key_persons:
                        - Sam Altman
                - name: Stripe
                  entity_type: company
                  description: Online payment processing platform
                  additional_attributes:
                    company_attributes:
                      domain: stripe.com
                      key_persons:
                        - Patrick Collison
                        - John Collison
      responses:
        "200":
          $ref: "#/components/responses/CreateEntitiesBatchResponse"
        "400":
          $ref: "#/components/responses/EntityBadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"

  /catchAll/entities/{entity_id}:
    get:
      tags:
        - Entities
      summary: Get entity
      description:
        Returns a single entity by ID with all attributes and current status.
      operationId: getEntity
      parameters:
        - $ref: "#/components/parameters/EntityId"
      responses:
        "200":
          $ref: "#/components/responses/EntityResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

    patch:
      tags:
        - Entities
      summary: Update entity
      description: |
        Updates one or more fields of an existing entity.
      operationId: updateEntity
      parameters:
        - $ref: "#/components/parameters/EntityId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEntityRequest"
            example:
              description: Updated description
              additional_attributes:
                company_attributes:
                  alternative_names:
                    - NC
                    - NewsCatcher API
                    - NCA
      responses:
        "200":
          $ref: "#/components/responses/EntityResponse"
        "400":
          $ref: "#/components/responses/EntityBadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

    delete:
      tags:
        - Entities
      summary: Delete entity
      description: |
        Permanently deletes an entity. The entity is removed from all
        datasets and the search index. This operation cannot be undone.
      operationId: deleteEntity
      parameters:
        - $ref: "#/components/parameters/EntityId"
      responses:
        "204":
          description: Entity deleted successfully. No response body.
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # ── Datasets ──────────────────────────────────────────────────────────────

  /catchAll/datasets:
    get:
      tags:
        - Datasets
      summary: List datasets
      description: |
        Returns a paginated list of datasets belonging to the authenticated organization. Supports filtering by status and sorting by name, status, or creation date.
      operationId: listDatasets
      parameters:
        - $ref: "#/components/parameters/Page"
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
          description: Number of datasets per page.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description:
            Filter datasets by name (case-insensitive substring match).
          example: Portfolio
        - name: latest_status
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/DatasetStatus"
          description: |
            Filter by dataset status.
        - name: sort_by
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/DatasetSortBy"
        - name: sort_order
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SortOrder"
        - $ref: "#/components/parameters/Ownership"
        - $ref: "#/components/parameters/ProjectIdQuery"
      responses:
        "200":
          $ref: "#/components/responses/DatasetListResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"

    post:
      tags:
        - Datasets
      summary: Create dataset
      description: |
        Creates a new dataset from a list of existing entity IDs.

        If any of the provided entity IDs do not exist or do not belong to
        your organization, the request fails with `400`. All entity IDs must
        be valid before the dataset is created.

        To create a dataset and entities in one step, use the [`Create dataset from CSV`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/datasets/create-dataset-from-csv)
        endpoint instead.
      operationId: createDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDatasetRequest"
            example:
              name: My Portfolio
              description: Companies in our investment portfolio
              entity_ids:
                - 854198fa-f702-49db-a381-0427fa87f173
                - a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        "200":
          $ref: "#/components/responses/DatasetResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/datasets/upload:
    post:
      tags:
        - Datasets
      summary: Create dataset from CSV
      description: |
        Creates a new dataset by uploading a CSV file. Each row in the CSV becomes an entity. The `name` and `domain`columns are required; all other columns are optional.

        **CSV format:**
        ```csv
        name,description,domain,alternative_names,key_persons
        NewsCatcher,"AI-powered news data provider",newscatcherapi.com,"NC;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
        OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"
        ```

        Use semicolons (`;`) to separate multiple values in `alternative_names` and `key_persons`. Rows with empty `name` are skipped and reported in `validation_report`. 

        **Note**: The response shape differs from the JSON dataset creation endpoint: it returns `dataset_id` (not `id`) and includes a `validation_report` with details on skipped rows.
      operationId: createDatasetFromCsv
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - name
              properties:
                file:
                  type: string
                  format: binary
                  description: The CSV file to upload.
                name:
                  type: string
                  description: Name for the new dataset.
                  example: My Portfolio
                description:
                  type: string
                  description: Optional description for the dataset.
                  example: Companies from Q1 2026 watchlist
      responses:
        "200":
          $ref: "#/components/responses/CreateDatasetCsvResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/datasets/{dataset_id}:
    get:
      tags:
        - Datasets
      summary: Get dataset
      description:
        Returns a single dataset by ID including entity count and current status.
      operationId: getDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      responses:
        "200":
          $ref: "#/components/responses/DatasetResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

    patch:
      tags:
        - Datasets
      summary: Update dataset
      description: |
        Updates the name or description of a dataset.
      operationId: updateDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDatasetRequest"
            example:
              name: My Portfolio (updated)
              description: Updated Q1 2026 watchlist
      responses:
        "200":
          $ref: "#/components/responses/DatasetResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      tags:
        - Datasets
      summary: Delete dataset
      description: |
        Permanently deletes a dataset. The entities within the dataset are
        not deleted — only the dataset itself. This operation cannot be
        undone.
      operationId: deleteDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      responses:
        "204":
          description: Dataset deleted successfully. No response body.
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/datasets/{dataset_id}/entities:
    post:
      tags:
        - Datasets
      summary: Add entities to dataset
      description: |
        Adds one or more existing entities to a dataset. Returns the number of entities added.
      operationId: addEntitiesToDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DatasetEntityIdsRequest"
            example:
              entity_ids:
                - 854198fa-f702-49db-a381-0427fa87f173
      responses:
        "200":
          $ref: "#/components/responses/ManageEntitiesResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      tags:
        - Datasets
      summary: Remove entities from dataset
      description: |
        Removes one or more entities from a dataset. The entities themselves are not deleted — they are only removed from this dataset. Returns the number of entities removed.
      operationId: removeEntitiesFromDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DatasetEntityIdsRequest"
            example:
              entity_ids:
                - 854198fa-f702-49db-a381-0427fa87f173
      responses:
        "200":
          $ref: "#/components/responses/ManageEntitiesResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/datasets/{dataset_id}/entities/list:
    post:
      tags:
        - Datasets
      summary: List entities in dataset
      description: |
        Returns a paginated list of entities in a dataset. Supports filtering by status, entity type, and name search.
      operationId: listEntitiesInDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListDatasetEntitiesRequest"
            example:
              page: 1
              page_size: 100
              search: "OpenAI"
              status: "ready"
              entity_type: "company"
              sort_by: "created_at"
              sort_order: "desc"
      responses:
        "200":
          $ref: "#/components/responses/DatasetEntityListResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/datasets/{dataset_id}/status:
    get:
      tags:
        - Datasets
      summary: Get dataset status history
      description: |
        Returns the full status change history for a dataset, ordered chronologically from oldest to newest.
      operationId: getDatasetStatusHistory
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      responses:
        "200":
          $ref: "#/components/responses/DatasetStatusHistoryResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/datasets/{dataset_id}/upload:
    post:
      tags:
        - Datasets
      summary: Add companies to dataset via CSV
      description: |
        Appends new companies to an existing dataset by uploading a CSV file. Uses the same CSV format as the dataset creation endpoint.

        The response omits `dataset_name` compared to the create-from-CSV endpoint since the dataset already exists.
      operationId: uploadCSVToDataset
      parameters:
        - $ref: "#/components/parameters/DatasetId"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The CSV file to upload.
      responses:
        "200":
          $ref: "#/components/responses/UploadCsvToDatasetResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

# ── Projects ──────────────────────────────────────────────────────────

  /catchAll/projects:
    post:
      tags:
        - Projects
      summary: Create project
      description: Creates a new project.
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectRequestDto"
            example:
              name: "AI M&A Tracking"
              description: "Tracks AI-related M&A activity for our investment team."
      responses:
        "201":
          $ref: "#/components/responses/CreateProjectResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

    get:
      tags:
        - Projects
      summary: List projects
      description: Returns all projects visible to the authenticated user.
      operationId: listProjects
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Filter by project name (case-insensitive substring match).
          example: "M&A"
        - $ref: "#/components/parameters/Ownership"
      responses:
        "200":
          $ref: "#/components/responses/ListProjectsResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/projects/{project_id}:
    get:
      tags:
        - Projects
      summary: Get project
      description: Returns a single project by ID.
      operationId: getProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/ProjectResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

    patch:
      tags:
        - Projects
      summary: Update project
      description: Updates the name or description of an existing project.
      operationId: updateProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectRequestDto"
            example:
              name: "AI M&A Tracking (Q2 2026)"
      responses:
        "200":
          $ref: "#/components/responses/UpdateProjectResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      tags:
        - Projects
      summary: Delete project
      description: |
        Deletes a project. By default, assigned resources are unassigned but not deleted. 
      operationId: deleteProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - $ref: "#/components/parameters/DeleteResources"
      responses:
        "204":
          description: Project deleted successfully. No response body.
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/projects/{project_id}/overview:
    get:
      tags:
        - Projects
      summary: Get project overview
      description: |
        Returns resource counts for a project, grouped by type and status.

        For `jobs` and `monitors`, counts are broken down by status (for example, `completed`, `failed`). For `datasets` and `monitor_groups`, only a `total` count is returned.
      operationId: getProjectOverview
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      responses:
        "200":
          $ref: "#/components/responses/ProjectOverviewResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /catchAll/projects/{project_id}/resources:
    post:
      tags:
        - Projects
      summary: Add resources to project
      description: |
        Assigns one or more existing resources to a project in a single request.
      operationId: addResourceToProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddResourceRequestDto"
            example:
              resources:
                - resource_type: "job"
                  resource_id: "48421e16-1f50-4048-b62c-d3bc0789d30d"
      responses:
        "200":
          $ref: "#/components/responses/AddResourceResponse"
        "201":
          $ref: "#/components/responses/AddResourceResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

    get:
      tags:
        - Projects
      summary: List project resources
      description: Returns all resources assigned to a project, with optional filtering by type.
      operationId: listProjectResources
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: resource_type
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/ProjectResourceType"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          $ref: "#/components/responses/ListProjectResourcesResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "422":
          $ref: "#/components/responses/ValidationError"

  /catchAll/projects/{project_id}/resources/{resource_type}/{resource_id}:
    delete:
      tags:
        - Projects
      summary: Remove resource from project
      description: |
        Removes a resource from a project. The resource itself is not
        deleted — it becomes unassigned and continues to exist.
      operationId: removeResourceFromProject
      parameters:
        - $ref: "#/components/parameters/ProjectId"
        - name: resource_type
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ProjectResourceType"
        - name: resource_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID of the resource to remove.
          example: "48421e16-1f50-4048-b62c-d3bc0789d30d"
      responses:
        "200":
          $ref: "#/components/responses/RemoveResourceResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # ── Meta ──────────────────────────────────────────────────────────────

  /health:
    get:
      tags:
        - Meta
      summary: Check health
      description: Check API availability.
      operationId: healthCheck
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HealthCheckResponse"

  /version:
    get:
      tags:
        - Meta
      summary: Get version
      description: Returns current API version.
      operationId: getVersion
      security: []
      responses:
        "200":
          $ref: "#/components/responses/VersionResponse"

  /catchAll/user/limits:
    post:
      tags:
        - Meta
      summary: Get plan limits
      description: |
        Returns plan features and current usage for the authenticated organization.
      operationId: getPlanLimits
      responses:
        "200":
          $ref: "#/components/responses/GetPlanLimitsResponse"
        "403":
          $ref: "#/components/responses/ForbiddenError"

components:
  parameters:
    JobId:
      name: job_id
      in: path
      required: true
      description: |
        Unique job identifier returned from [`POST /catchAll/submit`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/jobs/create-job).
      schema:
        type: string
        format: uuid
      example: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"

    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
      description: |
        Page number to retrieve.

    PageSize:
      name: page_size
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      description: |
        Number of records per page.

    EntityId:
      name: entity_id
      in: path
      required: true
      description: Unique entity identifier.
      schema:
        type: string
        format: uuid
      example: "854198fa-f702-49db-a381-0427fa87f173"

    DatasetId:
      name: dataset_id
      in: path
      required: true
      description: Unique dataset identifier.
      schema:
        type: string
        format: uuid
      example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"

    Search:
      name: search
      in: query
      required: false
      schema:
        type: string
      description: Filter results by text (case-insensitive substring match).

    Ownership:
      name: ownership
      in: query
      required: false
      schema:
        $ref: "#/components/schemas/OwnershipFilter"

    ProjectId:
      name: project_id
      in: path
      required: true
      description: Unique project identifier.
      schema:
        type: string
        format: uuid
      example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"

    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"

    DeleteResources:
      name: delete_resources
      in: query
      required: false
      description: |
        If true, permanently deletes all resources (jobs, monitors, datasets) assigned to the project. If false, the project is deleted and its resources are unassigned but not deleted.
      schema:
        type: boolean
        default: false

    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: Unique webhook identifier.
      schema:
        type: string
        format: uuid
      example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

    WebhookResourceType:
      name: resource_type
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/MappableResourceType"

    WebhookResourceId:
      name: resource_id
      in: path
      required: true
      description: Unique resource identifier.
      schema:
        type: string
        format: uuid
      example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"

  responses:
    ValidateQueryResponse:
      description: Query validation result.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ValidateQueryResponseDto"
          example:
            status: "good"
            title: "Specific event type clear"
            description: "Clear event type and focus; no timeframe needed for a default recent search."
            issues: []
            suggestions: []
            confidence: 0.98

    InitializeResponse:
      description: Suggestions retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InitializeResponseDto"
          example:
            query: "Series B funding rounds for SaaS startups"
            context: "Focus on funding amount and company name"
            validators:
              - name: "is_series_b_funding"
                description:
                  "true if the web page describes a Series B funding round"
                type: "boolean"
              - name: "is_saas_startup"
                description:
                  "true if the company receiving funding is a SaaS startup"
                type: "boolean"
            enrichments:
              - name: "funding_amount"
                description:
                  "Extract the amount of funding received in the Series B round"
                type: "number"
              - name: "investee_company"
                description:
                  "Extract the name of the SaaS startup receiving the funding"
                type: "company"
              - name: "investor_company"
                description: "Extract the name of the lead investor"
                type: "company"
              - name: "funding_date"
                description:
                  "Extract the date when the funding round was announced"
                type: "date"
            start_date: "2026-02-19T00:00:00Z"
            end_date: "2026-02-24T00:00:00Z"
            date_modification_message:
              - "No dates were provided; using a default window of 5 days."

    SubmitResponse:
      description: Job created successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SubmitResponseDto"
          example:
            job_id: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"

    ContinueResponse:
      description: Job continuation accepted
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ContinueResponseDto"
          example:
            job_id: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
            previous_limit: 10
            new_limit: 100
            status: "accepted"

    StatusResponse:
      description: Status retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusResponseDto"
          example:
            job_id: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
            status: "completed"
            steps:
              - status: "submitted"
                order: 1
                completed: true
              - status: "analyzing"
                order: 2
                completed: true
              - status: "fetching"
                order: 3
                completed: true
              - status: "clustering"
                order: 4
                completed: true
              - status: "enriching"
                order: 5
                completed: true
              - status: "completed"
                order: 6
                completed: true
              - status: "failed"
                order: 7
                completed: false

    ListUserJobsResponse:
      description: User jobs retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListUserJobsResponseDto"
          example:
            total: 27
            page: 1
            page_size: 2
            total_pages: 14
            jobs:
              - job_id: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
                query: "Series B funding rounds for SaaS startups"
                created_at: "2026-02-24T13:57:56Z"
                status: "completed"
                user_key: "***...a1b2"
                mode: "base"
              - job_id: "8d618890-f9f5-4c97-af17-236136a306a7"
                query: "Corporate headquarters relocations in the US"
                created_at: "2026-02-18T20:25:20Z"
                status: "completed"
                user_key: "***...a1b2"
                mode: "base"

    PullJobResponse:
      description: Results retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PullJobResponseDto"
          example:
            job_id: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
            query: "Series B funding rounds for SaaS startups"
            context: "Focus on funding amount and company name"
            validators: []
            enrichments: []
            status: "completed"
            error: null
            duration: "1m"
            candidate_records: 4
            valid_records: 3
            progress_validated: 4
            date_range:
              start_date: "2026-02-18T00:00:00Z"
              end_date: "2026-02-23T00:00:00Z"
            page: 1
            page_size: 2
            total_pages: 2
            limit: 10
            mode: "base"
            all_records:
              - record_id: "6983973854314692457"
                record_title: "VulnCheck Raises $25M Series B Funding"
                enrichment:
                  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
                citations:
                  - title: "VulnCheck raises $25M Series B"
                    link: "https://www.msn.com/en-us/money/other/exclusive-vulncheck-raises-25m-funding-to-help-companies-patch-software-bugs/ar-AA1WwdjW"
                    published_date: "2026-02-17T14:01:05Z"

    DeleteJobResponse:
      description: Job deleted successfully (or already deleted).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeleteJobResponseDto"
          example:
            success: true
            message: "Job deleted successfully."
            job_id: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

    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"

    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"

    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"

    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

    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.

    PullMonitorResponse:
      description: Monitor results retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PullMonitorResponseDto"

    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"

    CreateEntityResponse:
      description: Entity created successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateEntityResponse"
          example:
            id: "854198fa-f702-49db-a381-0427fa87f173"
            status: pending

    EntityResponse:
      description: Full entity object with all attributes and metadata.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EntityResponse"
          example:
            id: "854198fa-f702-49db-a381-0427fa87f173"
            entity_type: company
            organization_id: "e5d9e9b0-e415-4941-8ef0-916c5ee56207"
            name: NewsCatcher
            description: AI-powered news data provider
            additional_attributes:
              company_attributes:
                domain: newscatcherapi.com
                description: Provider of news and web search APIs for developers
                key_persons:
                  - Artem Bugara
                  - Maksym Sugonyaka
                alternative_names:
                  - NC
                  - NewsCatcher API
            status: ready
            created_by_user_id: "870e258e-12ec-4a47-8656-e7a43b0265b3"
            created_at: "2026-04-08T15:21:17.272139"
            updated_at: "2026-04-08T15:21:18.248316"

    EntityListResponse:
      description: Paginated list of entities.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EntityListResponse"

    CreateEntitiesBatchResponse:
      description: Batch of entities created successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateEntitiesBatchResponse"
          example:
            entities:
              - id: "88430468-d784-485d-84d5-6964a29ccd1e"
                status: pending
              - id: "ad4908fe-6db5-4237-a137-68dd8fc9fedc"
                status: pending
            count: 2

    DatasetResponse:
      description: Full dataset object with metadata and current status.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DatasetResponse"
          example:
            id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
            organization_id: "e5d9e9b0-e415-4941-8ef0-916c5ee56207"
            name: My Portfolio
            description: Companies in our investment portfolio
            entity_count: 4
            latest_status: ready
            created_by_user_id: "870e258e-12ec-4a47-8656-e7a43b0265b3"
            created_at: "2026-04-08T15:21:36.026993"
            updated_at: "2026-04-08T15:21:36.027001"

    DatasetListResponse:
      description: Paginated list of datasets.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DatasetListResponse"

    CreateDatasetCsvResponse:
      description: Dataset created from CSV successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateDatasetCsvResponse"
          example:
            dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
            dataset_name: My Portfolio
            entities_created: 3
            validation_report:
              total_rows: 4
              valid_rows: 3
              skipped_count: 1
              skipped_rows:
                - row: 3
                  reason: "missing required field: name"

    UploadCsvToDatasetResponse:
      description: Companies added to dataset from CSV successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UploadCsvToDatasetResponse"
          example:
            dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
            entities_created: 3
            validation_report:
              total_rows: 3
              valid_rows: 3
              skipped_count: 0
              skipped_rows: []

    ManageEntitiesResponse:
      description: Entities added or removed successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ManageEntitiesResponse"
          example:
            dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
            affected_count: 1

    DatasetEntityListResponse:
      description: Paginated list of entities in a dataset.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DatasetEntityListResponse"

    DatasetStatusHistoryResponse:
      description: Dataset status change history.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DatasetStatusHistoryResponse"
          example:
            dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
            history:
              - status: pending
                additional_information: null
                created_at: "2026-04-08T15:21:36.066271"
              - status: enriching
                additional_information: null
                created_at: "2026-04-08T15:21:36.500000"
              - status: ready
                additional_information: null
                created_at: "2026-04-08T15:21:55.000000"

    HealthCheckResponse:
      description: API is healthy
      content:
        application/json:
          schema:
            type: object
            properties:
              healthy:
                type: boolean
                example: true

    VersionResponse:
      description: API version
      content:
        application/json:
          schema:
            type: object
            properties:
              version:
                type: string
                example: "1.3.1"

    GetPlanLimitsResponse:
      description: Plan limits retrieved successfully
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GetPlanLimitsResponseDto"
          example:
            features:
              - name: "Jobs Concurrency"
                code: "Jobs_Concurrency"
                value_type: "integer"
                value: 20
                current_usage: 1
              - name: "Max Results"
                code: "Job_Max_Results"
                value_type: "integer"
                value: 100000
                current_usage: 0
              - name: "Monthly Granted Credits"
                code: "monthly_free_credits"
                value_type: "integer"
                value: 200000
                current_usage: 0

    # ── Webhook responses ────────────────────────────────────────────────

    CreateWebhookResponse:
      description: Webhook created successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateWebhookResponseDto"
          example:
            success: true
            message: "Webhook created successfully."
            webhook:
              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              name: "Layoffs Alert"
              url: "https://hooks.slack.com/services/T000/B000/xxx"
              type: "slack"
              delivery_mode: "full"
              method: "POST"
              headers: {}
              params: {}
              formatter_config: null
              is_active: true
              organization_id: "org-uuid-here"
              created_by_user_id: "user-uuid-here"
              created_at: "2026-05-18T10:00:00Z"
              updated_at: "2026-05-18T10:00:00Z"

    GetWebhookResponse:
      description: Webhook retrieved successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GetWebhookResponseDto"
          example:
            success: true
            message: "Webhook retrieved successfully."
            webhook:
              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              name: "Layoffs Alert"
              url: "https://hooks.slack.com/services/T000/B000/xxx"
              type: "slack"
              delivery_mode: "full"
              method: "POST"
              headers: {}
              params: {}
              formatter_config: null
              is_active: true
              organization_id: "org-uuid-here"
              created_by_user_id: "user-uuid-here"
              created_at: "2026-05-18T10:00:00Z"
              updated_at: "2026-05-18T10:00:00Z"

    UpdateWebhookResponse:
      description: Webhook updated successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateWebhookResponseDto"
          example:
            success: true
            message: "Webhook updated successfully."
            webhook:
              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              name: "Layoffs Alert (EU)"
              url: "https://hooks.slack.com/services/T000/B111/yyyy"
              type: "slack"
              delivery_mode: "full"
              method: "POST"
              headers: {}
              params: {}
              formatter_config: null
              is_active: true
              organization_id: "org-uuid-here"
              created_by_user_id: "user-uuid-here"
              created_at: "2026-05-18T10:00:00Z"
              updated_at: "2026-05-19T08:30:00Z"

    ListWebhooksResponse:
      description: Webhooks retrieved successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListWebhooksResponseDto"
          example:
            total: 2
            page: 1
            page_size: 100
            total_pages: 1
            webhooks:
              - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "Layoffs Alert"
                url: "https://hooks.slack.com/services/T000/B000/xxx"
                type: "slack"
                delivery_mode: "full"
                method: "POST"
                headers: {}
                params: {}
                formatter_config: null
                is_active: true
                organization_id: "org-uuid-here"
                created_by_user_id: "user-uuid-here"
                created_at: "2026-05-18T10:00:00Z"
                updated_at: "2026-05-18T10:00:00Z"
              - id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                name: "M&A Tracker"
                url: "https://my-service.example.com/catchall-hook"
                type: "generic"
                delivery_mode: "per_record"
                method: "POST"
                headers:
                  Authorization: "Bearer token123"
                params: {}
                formatter_config: null
                is_active: true
                organization_id: "org-uuid-here"
                created_by_user_id: "user-uuid-here"
                created_at: "2026-05-19T09:00:00Z"
                updated_at: "2026-05-19T09:00:00Z"

    TestWebhookResponse:
      description: Test delivery attempted. Check `success` and `http_status_code` for the outcome.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TestWebhookResponseDto"
          example:
            success: true
            message: "Test delivery succeeded."
            http_status_code: 200
            response_body: "ok"

    AssignWebhookResourceResponse:
      description: Resource assigned to webhook.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AssignWebhookResourceResponseDto"
          example:
            success: true
            message: "Resource assigned to webhook."
            already_existed: false
            mapping:
              id: "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
              webhook_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              resource_type: "monitor"
              resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
              assigned_at: "2026-05-18T10:00:00Z"

    ListWebhookResourcesResponse:
      description: Webhook resource assignments retrieved successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListWebhookResourcesResponseDto"
          example:
            total: 1
            page: 1
            page_size: 100
            total_pages: 1
            resources:
              - id: "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
                webhook_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                resource_type: "monitor"
                resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
                assigned_at: "2026-05-18T10:00:00Z"

    ListResourceWebhooksResponse:
      description: Webhooks for resource retrieved successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ListWebhooksResponseDto"
          example:
            total: 1
            page: 1
            page_size: 100
            total_pages: 1
            webhooks:
              - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                name: "Layoffs Alert"
                url: "https://hooks.slack.com/services/T000/B000/xxx"
                type: "slack"
                delivery_mode: "full"
                method: "POST"
                headers: {}
                params: {}
                formatter_config: null
                is_active: true
                organization_id: "org-uuid-here"
                created_by_user_id: "user-uuid-here"
                created_at: "2026-05-18T10:00:00Z"
                updated_at: "2026-05-18T10:00:00Z"

    DeliveryHistoryResponse:
      description: Webhook delivery history retrieved successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeliveryHistoryResponseDto"
          example:
            resource_type: "monitor"
            resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
            total: 2
            page: 1
            page_size: 50
            total_pages: 1
            items:
              - id: 42
                webhook_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                resource_type: "monitor"
                resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
                additional_info: {}
                status_code: 200
                attempt_number: 1
                timestamp: "2026-05-18T10:00:00Z"
                delivery_status: "SUCCESS"
                error_message: null
                warning_message: null
              - id: 41
                webhook_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                resource_type: "monitor"
                resource_id: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
                additional_info: {}
                status_code: 503
                attempt_number: 1
                timestamp: "2026-05-17T10:00:00Z"
                delivery_status: "FAILED"
                error_message: "Service unavailable"
                warning_message: null

    # ── Project responses ────────────────────────────────────────────────

    CreateProjectResponse:
      description: Project created successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateProjectResponseDto"
          example:
            success: true
            message: "Project created successfully."
            project_id: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
            name: "AI M&A Tracking"

    ProjectResponse:
      description: Project details.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectResponseDto"
          example:
            success: true
            message: "OK"
            project_id: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
            name: "AI M&A Tracking"
            description: "Tracks AI-related M&A activity for our investment team."
            resources_count: 4
            created_at: "2026-05-20T14:31:35Z"
            updated_at: "2026-05-20T14:31:35Z"

    UpdateProjectResponse:
      description: Project updated successfully.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateProjectResponseDto"
          example:
            success: true
            message: "Project updated successfully."
            project_id: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"

    ListProjectsResponse:
      description: Paginated list of projects.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectListResponseDto"
          example:
            total: 2
            page: 1
            page_size: 100
            total_pages: 1
            projects:
              - project_id: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
                name: "AI M&A Tracking"
                description: "Tracks AI-related M&A activity."
                resources_count: 4
                created_at: "2026-05-20T14:31:35Z"
                updated_at: "2026-05-20T14:31:35Z"

    ProjectOverviewResponse:
      description: Resource counts for the project, grouped by type and status.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectOverviewResponseDto"
          example:
            project_id: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
            overview:
              jobs: {}
              monitors: {}
              datasets:
                total: 2
              monitor_groups:
                total: 0

    AddResourceResponse:
      description: |
        One or more resources added to the project (`201`), or all were already present (`200`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AddResourceResponseDto"
          example:
            success: true
            message: "Resources added to project."
            results:
              - resource_type: "job"
                resource_id: "48421e16-1f50-4048-b62c-d3bc0789d30d"
                success: true
                message: "Resource added to project."
                already_exists: false

    ListProjectResourcesResponse:
      description: Paginated list of resources assigned to the project.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProjectResourceListResponseDto"
          example:
            total: 1
            page: 1
            page_size: 100
            total_pages: 1
            resources:
              - resource_type: "job"
                resource_id: "48421e16-1f50-4048-b62c-d3bc0789d30d"
                name: "Series B fintech funding rounds"
                created_at: "2026-05-20T14:31:37Z"
                metadata: {}

    RemoveResourceResponse:
      description: Resource removed from the project.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/RemoveResourceResponseDto"
          example:
            success: true
            message: "Resource removed from project."

    # ── Common error responses ─────────────────────────────────────────────

    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."

    EntityBadRequestError:
      description: |
        Validation error in entity field values.

        Returned when required fields are missing or field values are invalid
        (for example, an unrecognised `entity_type` value). The response body
        uses a `message`/`status`/`status_code` structure, distinct from the
        standard `detail`-based error format used elsewhere in the API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EntityValidationErrorBody"
          examples:
            missing_name:
              summary: Required field missing
              value:
                message:
                  "Validation Error with the following fields: [{'field':
                  'body.name', 'message': 'field required', 'type':
                  'value_error.missing'}]"
                status: Bad Request
                status_code: 400
            invalid_entity_type:
              summary: Invalid enum value
              value:
                message:
                  'Validation Error with the following fields: [{''field'':
                  ''body.entity_type'', ''message'': "entity_type must be one of
                  (''company'', ''person'')", ''type'': ''value_error''}]'
                status: Bad Request
                status_code: 400

    ForbiddenError:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    NotFoundError:
      description: Job/monitor not found or results not available
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ValidationErrorResponse"

    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"

  schemas:
    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.

    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.

    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.

    CompanyEnrichmentOutput:
      type: object
      description: |
        Appears as the value of company-typed fields in the `enrichment` object of each record. The `metadata` sub-object is populated by the system based on the identified company.
      required:
        - source_text
        - confidence
        - metadata
      properties:
        source_text:
          type: string
          description:
            The text span in the source document where the company was
            identified.
          example: "Sorenson Capital"
        confidence:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Confidence score for the company identification.
          example: 0.99
        metadata:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Normalized company name.
              example: "Sorenson Capital"
            domain_url:
              type: [string, "null"]
              description: Company website domain if resolved, otherwise null.
              example: "vulncheck.com"
            domain_url_confidence:
              type: [string, "null"]
              enum: ["low", "medium", "high", null]
              description: Confidence level for the domain URL resolution.
              example: "high"

    QueryStatus:
      type: string
      enum:
        - good
        - needs_work
        - critical
      description: |
        Quality level assigned to a query by the validation endpoint.

        - `good`: Query is well-formed and likely to produce relevant results.
        - `needs_work`: Query has issues that may reduce result quality. Review `suggestions` for improvements.
        - `critical`: Query is unlikely to produce useful results as written. Address all `issues` before submitting.

    IssueType:
      type: string
      enum:
        - missing_event_type
        - too_vague
        - too_specific
        - wrong_timeframe
        - static_content
        - article_request
        - multiple_event_types
        - too_short
        - too_long
      description: |
        Category of a query issue identified during validation.

        - `missing_event_type`: Query does not specify a type of event to find.
        - `too_vague`: Query lacks sufficient focus to return targeted results.
        - `too_specific`: Query is overly constrained and may return no results.
        - `wrong_timeframe`: Requested timeframe exceeds the 30-day maximum window or references a historical period outside the supported range.
        - `static_content`: Query targets static or reference content such as specifications, how-to guides, or historical data rather than events.
        - `article_request`: Query requests articles or news content rather than describing an event to search for.
        - `multiple_event_types`: Query mixes unrelated event types; results may be unfocused.
        - `too_short`: Query is too short to resolve meaningful search intent.
        - `too_long`: Query is excessively long and may confuse the pipeline.

    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"

    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"

    ValidateQueryResponseDto:
      type: object
      description: Query quality assessment returned by the validate endpoint.
      required:
        - status
        - title
        - confidence
      properties:
        status:
          $ref: "#/components/schemas/QueryStatus"
          description: Overall quality level of the query.
        title:
          type: string
          description: Short headline summarising the assessment.
          example: "Specific event type clear"
        description:
          type: string
          description: Plain-language explanation of the assessment result.
          example: "Clear event type and focus; no timeframe needed for a default recent search."
        issues:
          type: array
          items:
            $ref: "#/components/schemas/IssueType"
          description: Issues identified in the query. Empty when `status` is `good`.
          example: []
        suggestions:
          type: array
          items:
            $ref: "#/components/schemas/Suggestion"
          description: |
            Actionable recommendations for each identified issue. Empty when `status` is `good`. Each suggestion corresponds to one entry in `issues`.
          example: []
        confidence:
          type: number
          minimum: 0
          maximum: 1
          description: Confidence score for this assessment.
          example: 0.98

    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.

    InitializeResponseDto:
      type: object
      required:
        - query
        - validators
        - enrichments
      properties:
        query:
          type: string
          description: Echo of the query from the request.
          example: "Series B funding rounds for SaaS startups"
        context:
          type: [string, "null"]
          description:
            Echo of the context from the request. Null if not provided.
          example: "Focus on funding amount and company name"
        validators:
          type: array
          items:
            $ref: "#/components/schemas/ValidatorSchema"
          description: Suggested validators for filtering relevant web pages.
          minItems: 0
        enrichments:
          type: array
          items:
            $ref: "#/components/schemas/EnrichmentSchema"
          description: Suggested enrichment fields for data extraction.
          minItems: 0
        start_date:
          $ref: "#/components/schemas/StartDate"
        end_date:
          $ref: "#/components/schemas/EndDate"
        date_modification_message:
          type: array
          items:
            type: string
          description: |
            Messages explaining date adjustments due to plan limits.

            Empty array if no modifications were needed. Contains human-readable messages when requested dates exceed plan's allowed lookback period.
          default: []
          example:
            - "start_date must be >= 2025-01-23, your plan limited to lookback
              365 days; we modified start_date to 2025-01-23."

    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.

    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"

    ContinueRequestDto:
      type: object
      required:
        - job_id
      properties:
        job_id:
          type: string
          format: uuid
          description: |
            Job identifier of the completed job to continue.
          example: "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
        new_limit:
          type: integer
          description: |
            New record limit for continued processing. Must be greater than the previous limit. If not provided, defaults to the plan maximum.
          example: 100

    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"

    DeleteJobResponseDto:
      type: object
      required:
        - success
        - message
        - job_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: "Job deleted successfully."
        job_id:
          type: ["string", "null"]
          format: uuid
          description: ID of the deleted job. `null` on failure.
          example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

    PublicJobStatus:
      type: string
      enum:
        - submitted
        - analyzing
        - fetching
        - clustering
        - enriching
        - completed
        - failed
      description: |
        Current job processing status. Jobs progress through these stages:

        - `submitted`: Job queued, waiting to start processing.
        - `analyzing`: Extracting keywords, generating search queries, and creating validators/extractors.
        - `fetching`: Retrieving web pages.
        - `clustering`: Grouping similar web pages into clusters.
        - `enriching`: Validating clusters and extracting structured data.
        - `completed`: Job finished successfully, results ready.
        - `failed`: Job processing failed.

        Poll `/catchAll/status/{job_id}` every 30-60 seconds until status is `completed` (typically 10-15 minutes).
      example: "fetching"

    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.

    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.

    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"

    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.

    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.

            **Note:** The system always includes the `enrichment_confidence` field within the `enrichment` object, regardless of whether enrichments are generated or specified by you.

             For integration guidance, see [Dynamic schemas](https://www.newscatcherapi.com/docs/web-search-api/guides-and-concepts/dynamic-schemas)
          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"

    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`.

    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"

    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.

    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.

    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.

            If the schedule includes a timezone abbreviation (for example, `"every day at 9am EST"`), the parsed timezone takes priority and this value is ignored. 
          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. 

            If false, no gap filling occurs and the first run uses the current cron window only — the reference job's age does not matter.
        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"

    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].

    WebhookType:
      type: string
      enum:
        - generic
        - slack
        - teams
        - custom
      description: |
        Webhook target type.

        - `generic`: Sends the raw result payload to any HTTPS endpoint.
        - `slack`: Sends a formatted Slack Block Kit message. URL must start with `https://hooks.slack.com/`.
        - `teams`: Sends a formatted Microsoft Teams Adaptive Card. URL hostname must match `*webhook.office.com` or `*.webhook.office365.com`.
        - `custom`: Sends a transformed payload using the configuration in `formatter_config`. Requires `formatter_config` to be set.

        When `type` is omitted, it is auto-detected from the URL.

    DeliveryMode:
      type: string
      enum:
        - full
        - per_record
      description: |
        Delivery mode for webhook payloads.

        - `full`: Sends all records in a single request on each trigger.
        - `per_record`: Sends one request per record. For large result sets, this may generate many requests.
   
    HttpMethod:
      type: string
      enum:
        - GET
        - POST
        - PUT
        - PATCH
        - DELETE
      description: HTTP method used for webhook delivery.

    MappableResourceType:
      type: string
      enum:
        - job
        - monitor
        - monitor_group
      description: Resource types that can be assigned to a webhook.

    DeliveryStatus:
      type: string
      enum:
        - SUCCESS
        - FAILED
      description: Outcome of a webhook delivery attempt.

    DeliveryHistoryItemDto:
      type: object
      required:
        - id
        - webhook_id
        - resource_type
        - resource_id
        - status_code
        - attempt_number
        - timestamp
        - delivery_status
      properties:
        id:
          type: integer
          description: Delivery record identifier.
          example: 42
        webhook_id:
          type: string
          format: uuid
          description: Identifier of the webhook that was dispatched.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        resource_type:
          $ref: "#/components/schemas/MappableResourceType"
          description: Type of the resource that triggered the delivery.
        resource_id:
          type: string
          format: uuid
          description: Identifier of the resource that triggered the delivery.
          example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
        additional_info:
          type: object
          description: Extra context about the triggering event, such as job query or monitor schedule.
          example: {}
        status_code:
          type: integer
          description: HTTP response code returned by the webhook endpoint.
          example: 200
        attempt_number:
          type: integer
          description: Delivery attempt number. 1 indicates the first attempt.
          example: 1
        timestamp:
          type: string
          format: date-time
          description: Time of the delivery attempt in ISO 8601 format with UTC timezone.
          example: "2026-05-18T10:00:00Z"
        delivery_status:
          $ref: "#/components/schemas/DeliveryStatus"
          description: Outcome of this delivery attempt.
        error_message:
          type: ["string", "null"]
          description: Error detail when `delivery_status` is `FAILED`. Null on success.
          example: null
        warning_message:
          type: ["string", "null"]
          description: Non-fatal warning, such as payload truncation notices. Null when no warnings occurred.
          example: null

    DeliveryHistoryResponseDto:
      type: object
      required:
        - resource_type
        - resource_id
        - total
        - page
        - page_size
        - total_pages
        - items
      properties:
        resource_type:
          $ref: "#/components/schemas/MappableResourceType"
          description: Type of the queried resource.
        resource_id:
          type: string
          format: uuid
          description: Identifier of the queried resource.
          example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
        total:
          type: integer
          description: Total number of delivery records for this resource.
          example: 42
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of records per page.
          example: 50
        total_pages:
          type: integer
          description: Total number of pages available.
          example: 1
        items:
          type: array
          items:
            $ref: "#/components/schemas/DeliveryHistoryItemDto"
          description: Delivery records on this page, ordered by timestamp descending.

    BearerAuthDto:
      type: object
      required:
        - type
        - token
      properties:
        type:
          type: string
          enum:
            - bearer
          description: Authentication type.
        token:
          type: string
          description: Bearer token sent in the `Authorization` header.
          example: "my-secret-token"

    ApiKeyAuthDto:
      type: object
      required:
        - type
        - header
        - value
      properties:
        type:
          type: string
          enum:
            - api_key
          description: Authentication type.
        header:
          type: string
          description: HTTP header name for the API key.
          example: "x-api-key"
        value:
          type: string
          description: API key value.
          example: "sk-abc123"

    BasicAuthDto:
      type: object
      required:
        - type
        - username
        - password
      properties:
        type:
          type: string
          enum:
            - basic
          description: Authentication type.
        username:
          type: string
          description: Basic auth username.
          example: "user"
        password:
          type: string
          description: Basic auth password.
          example: "pass"

    WebhookResponseDto:
      type: object
      required:
        - id
        - name
        - url
        - type
        - delivery_mode
        - method
        - is_active
      properties:
        id:
          type: string
          format: uuid
          description: Webhook identifier.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        name:
          type: string
          description: Human-readable label for this webhook.
          example: "Layoffs Alert"
        url:
          type: string
          format: uri
          description: Destination URL that receives the payload.
          example: "https://hooks.slack.com/services/T000/B000/xxx"
        type:
          $ref: "#/components/schemas/WebhookType"
        delivery_mode:
          $ref: "#/components/schemas/DeliveryMode"
        method:
          $ref: "#/components/schemas/HttpMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom HTTP headers forwarded with each delivery.
          example:
            Authorization: "Bearer token123"
        params:
          type: object
          additionalProperties:
            type: string
          description: Query parameters appended to the webhook URL.
          example: {}
        formatter_config:
          type: ["object", "null"]
          description: Custom payload transformation configuration. Used only when `type` is `custom`.
          example: null
        is_active:
          type: boolean
          description: True if the webhook is active; false otherwise.
          example: true
        organization_id:
          type: string
          description: Organization that owns this webhook.
          example: "org-uuid-here"
        created_by_user_id:
          type: string
          description: ID of the user who created this webhook.
          example: "user-uuid-here"
        created_at:
          type: string
          format: date-time
          description: Webhook creation timestamp in ISO 8601 format with UTC timezone.
          example: "2026-05-18T10:00:00Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update in ISO 8601 format with UTC timezone.
          example: "2026-05-18T10:00:00Z"

    CreateWebhookRequestDto:
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
          description: Human-readable label for this webhook.
          example: "Layoffs Alert"
        url:
          type: string
          format: uri
          description: |
            Destination URL that receives the payload. Must use HTTPS. IP addresses are not accepted.

            Type-specific URL requirements:
            - `slack`: Must start with `https://hooks.slack.com/`.
            - `teams`: Hostname must match `*.webhook.office.com` or `*.webhook.office365.com`.
            - `generic`: Any valid HTTPS domain.
            - `custom`: Any valid HTTPS domain.

            When `type` is omitted, it is auto-detected from the URL.
          example: "https://hooks.slack.com/services/T000/B000/xxx"
        type:
          $ref: "#/components/schemas/WebhookType"
        delivery_mode:
          $ref: "#/components/schemas/DeliveryMode"
        method:
          $ref: "#/components/schemas/HttpMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom HTTP headers forwarded with each delivery.
          default: {}
        params:
          type: object
          additionalProperties:
            type: string
          description: Query parameters appended to the webhook URL.
          default: {}
        auth:
          oneOf:
            - $ref: "#/components/schemas/BearerAuthDto"
            - $ref: "#/components/schemas/ApiKeyAuthDto"
            - $ref: "#/components/schemas/BasicAuthDto"
          discriminator:
            propertyName: type
            mapping:
              bearer: "#/components/schemas/BearerAuthDto"
              api_key: "#/components/schemas/ApiKeyAuthDto"
              basic: "#/components/schemas/BasicAuthDto"
          description: |
            Authentication forwarded with each delivery. Supported types:
            - `bearer`: Adds an `Authorization: Bearer <token>` header.
            - `api_key`: Adds a custom header with the specified name and value.
            - `basic`: Adds an `Authorization: Basic <credentials>` header.
        formatter_config:
          type: ["object", "null"]
          description: Custom payload transformation configuration. Required only when `type` is `custom`.
      example:
        name: "Layoffs Alert"
        url: "https://hooks.slack.com/services/T000/B000/xxx"
        type: "slack"
        delivery_mode: "full"

    CreateWebhookResponseDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: True if the webhook was created; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Webhook created successfully."
        webhook:
          $ref: "#/components/schemas/WebhookResponseDto"
          description: The created webhook object.

    GetWebhookResponseDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Webhook retrieved successfully."
        webhook:
          $ref: "#/components/schemas/WebhookResponseDto"
          description: The retrieved webhook object.

    UpdateWebhookResponseDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: True if the webhook was updated; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Webhook updated successfully."
        webhook:
          $ref: "#/components/schemas/WebhookResponseDto"
          description: The updated webhook object.

    UpdateWebhookRequestDto:
      type: object
      description: All fields are optional. Only supplied fields are updated.
      properties:
        name:
          type: string
          description: Updated webhook name.
          example: "Layoffs Alert (EU)"
        url:
          type: string
          format: uri
          description: Updated destination URL. Must use HTTPS. Type-specific URL rules apply.
          example: "https://hooks.slack.com/services/T000/B111/yyyy"
        type:
          $ref: "#/components/schemas/WebhookType"
        delivery_mode:
          $ref: "#/components/schemas/DeliveryMode"
        method:
          $ref: "#/components/schemas/HttpMethod"
        headers:
          type: object
          additionalProperties:
            type: string
          description: Updated HTTP headers. Replaces existing headers entirely.
          example:
            Authorization: "Bearer new-token"
        params:
          type: object
          additionalProperties:
            type: string
          description: Updated query parameters. Replaces existing params entirely.
          example: {}
        auth:
          oneOf:
            - $ref: "#/components/schemas/BearerAuthDto"
            - $ref: "#/components/schemas/ApiKeyAuthDto"
            - $ref: "#/components/schemas/BasicAuthDto"
          discriminator:
            propertyName: type
            mapping:
              bearer: "#/components/schemas/BearerAuthDto"
              api_key: "#/components/schemas/ApiKeyAuthDto"
              basic: "#/components/schemas/BasicAuthDto"
          description: Updated authentication configuration. Replaces existing auth entirely.
        formatter_config:
          type: ["object", "null"]
          description: Updated formatter configuration.
        is_active:
          type: boolean
          description: Set to `false` to disable delivery without deleting the webhook.
          example: false

    ListWebhooksResponseDto:
      type: object
      required:
        - total
        - page
        - page_size
        - total_pages
        - webhooks
      properties:
        total:
          type: integer
          description: Total number of webhooks in the organization.
          example: 3
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of webhooks per page.
          example: 100
        total_pages:
          type: integer
          description: Total number of pages available.
          example: 1
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/WebhookResponseDto"
          description: Webhooks on this page.

    TestWebhookRequestDto:
      type: object
      properties:
        payload:
          type: object
          description: |
            Custom payload to send in the test request. If omitted, a synthetic
            test payload is sent.
          example:
            test: true
            message: "CatchAll webhook test"

    TestWebhookResponseDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: True if the test delivery received a 2xx response; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Test delivery succeeded."
        http_status_code:
          type: integer
          description: HTTP status code returned by the webhook endpoint.
          example: 200
        response_body:
          description: Response body returned by the webhook endpoint. Type varies by target.
          example: "ok"

    AssignWebhookResourceRequestDto:
      type: object
      required:
        - resource_type
        - resource_id
      properties:
        resource_type:
          $ref: "#/components/schemas/MappableResourceType"
          description: Type of resource to assign.
        resource_id:
          type: string
          format: uuid
          description: ID of the resource to assign.
          example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"

    WebhookResourceMappingResponseDto:
      type: object
      required:
        - id
        - webhook_id
        - resource_type
        - resource_id
      properties:
        id:
          type: string
          format: uuid
          description: Mapping identifier.
          example: "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
        webhook_id:
          type: string
          format: uuid
          description: Webhook identifier.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        resource_type:
          type: string
          description: Type of the assigned resource.
          example: "monitor"
        resource_id:
          type: string
          format: uuid
          description: Identifier of the assigned resource.
          example: "3fec5b07-8786-46d7-9486-d43ff67eccd4"
        assigned_at:
          type: string
          format: date-time
          description: Timestamp when the resource was assigned in ISO 8601 format with UTC timezone.
          example: "2026-05-18T10:00:00Z"

    AssignWebhookResourceResponseDto:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Resource assigned to webhook."
        already_existed:
          type: boolean
          description: True if the assignment already existed before this request.
          default: false
          example: false
        mapping:
          $ref: "#/components/schemas/WebhookResourceMappingResponseDto"
          description: The created or existing resource mapping.

    ListWebhookResourcesResponseDto:
      type: object
      required:
        - total
        - page
        - page_size
        - total_pages
        - resources
      properties:
        total:
          type: integer
          description: Total number of resource mappings for this webhook.
          example: 2
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of mappings per page.
          example: 100
        total_pages:
          type: integer
          description: Total number of pages available.
          example: 1
        resources:
          type: array
          items:
            $ref: "#/components/schemas/WebhookResourceMappingResponseDto"
          description: Resource mappings on this page.

    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"

    UpdateMonitorRequestDto:
      type: object
      properties:
        webhook_ids:
          type: array
          items:
            type: string
            format: uuid
          description: |
            Updated list of centralized webhook IDs for this monitor. 
            
            Replaces all existing webhook assignments. Pass an empty array `[]` to clear all assignments. Omit to leave existing assignments unchanged.
          example:
            - "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        limit:
          type: integer
          minimum: 10
          description: Updated maximum number of records per monitor run.

    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"

    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"

    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"

    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

    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.

    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.

    WebhookPayload:
      type: object
      description: |
        **First execution:** The initial webhook after monitor creation includes all records from the reference job, providing immediate access to collected data.

        **Subsequent executions:** Only new records (after deduplication) are included.
      properties:
        monitor_id:
          type: string
          format: uuid
          description: Monitor identifier.
        reference_job_id:
          type: string
          format: uuid
          description: Reference job used as template for this monitor.
        latest_job_id:
          type: string
          format: uuid
          description: Job ID of the most recent execution.
        records_count:
          type: integer
          description:
            Number of new records from latest job (after deduplication).
        jobs_processed:
          type: integer
          description: Total number of jobs executed by this monitor.
        updated_at:
          type: string
          format: date-time
          description:
            The date when the webhook was triggered in ISO 8601 format with UTC
            timezone.
          example: "2025-11-15T06:01:57Z"
        cron_expression:
          type: string
          description: Cron expression defining the monitor schedule.
        timezone:
          type: string
          description: Timezone for schedule execution.
        records:
          type: array
          items:
            $ref: "#/components/schemas/MonitorRecord"
          description:
            Array of new records from the latest job execution (includes
            monitor-specific fields like added_on, updated_on).

    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"

    MonitorStatusEntry:
      type: object
      required:
        - status
        - created_at
      properties:
        status:
          type: string
          enum:
            - created
            - enable
            - disable
            - scheduled
            - dump
          description: |
            Type of lifecycle event.

            - `created`: Monitor was created.
            - `enable`: Monitor was enabled.
            - `disable`: Monitor was disabled.
            - `scheduled`: A job was triggered for execution.
              `additional_information` contains `job_id`, `start_date`,
              and `end_date`.
            - `dump`: Results were collected after a job completed.
              `additional_information` contains `nb_existing_records`,
              `nb_final_records`, and optionally `webhook`.
        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.

            For `scheduled`:
            ```json
            {
              "job_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
              "start_date": "2026-02-04T12:00:00",
              "end_date": "2026-02-05T12:00:00"
            }
            ```

            For `dump`:
            ```json
            {
              "nb_existing_records": 408,
              "nb_final_records": 28,
              "webhook": {
                "success": true,
                "status_code": 200,
                "error_message": null
              }
            }
            ```
            The `webhook` key is only present if the monitor has a webhook configured.

    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.

    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. 

            If false, no gap filling occurs and the first run uses the current cron window only — the last job's age does not matter.

    # ── Shared ────────────────────────────────────────────────────────────────

    SortOrder:
      type: string
      enum:
        - asc
        - desc
      description: |
        Sort direction for list results.

        - `asc`: ascending (oldest or smallest first)
        - `desc`: descending (newest or largest first)
      default: desc

    OwnershipFilter:
      type: string
      enum:
        - all
        - own
        - shared
      default: all
      description: |
        Controls which resources are returned based on ownership.

        - `all`: Returns resources owned by the user and resources shared
          with them (default, backward compatible).
        - `own`: Returns only resources created by the authenticated user.
        - `shared`: Returns only resources shared with the user by others.

    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"

    # ── Entity enumerations ───────────────────────────────────────────────────

    EntityStatus:
      type: string
      enum:
        - pending
        - enriching
        - ready
        - failed
      description: |
        Processing status of an entity.

        - `pending`: Entity has been created and is queued for enrichment.
        - `enriching`: Enrichment is in progress.
        - `ready`: Enrichment complete — entity is indexed and ready for use in jobs.
        - `failed`: Enrichment failed. The entity may still be used but matching quality may be reduced.

    EntityType:
      type: string
      enum:
        - company
        - person
      description: |
        The type of entity.

        - `company`: A company or organization (default).
        - `person`: An individual person.
      default: company

    EntitySortBy:
      type: string
      enum:
        - created_at
        - name
        - status
      description: Fields available for sorting entity list results.
      default: created_at

    # ── Dataset enumerations ──────────────────────────────────────────────────

    DatasetStatus:
      type: string
      enum:
        - pending
        - enriching
        - ready
        - failed
      description: |
        Processing status of a dataset.

        - `pending`: Dataset created, entities queued for enrichment.
        - `enriching`: Entities are being enriched.
        - `ready`: All entities enriched and indexed — ready for use in jobs.
        - `failed`: One or more entity enrichments failed.

    DatasetSortBy:
      type: string
      enum:
        - name
        - created_at
        - status
      description: Fields available for sorting dataset list results.
      default: created_at

    # ── Error schemas ─────────────────────────────────────────────────────────

    EntityValidationErrorBody:
      type: object
      required:
        - message
        - status
        - status_code
      description: |
        Error body returned by entity endpoints for field-level validation
        failures. Uses a different structure from the standard `Error` schema
        (`{"detail": "..."}`) used elsewhere in the API.
      properties:
        message:
          type: string
          description: |
            Human-readable description of all validation errors, including
            field path, failure message, and error type.
          example:
            'Validation Error with the following fields: [{''field'':
            ''body.entity_type'', ''message'': "entity_type must be one of
            (''company'', ''person'')", ''type'': ''value_error''}]'
        status:
          type: string
          description: HTTP status text.
          example: Bad Request
        status_code:
          type: integer
          description: HTTP status code.
          example: 400

    # ── Entity request/response schemas ──────────────────────────────────────

    CompanyAttributes:
      type: object
      description: |
        Identifying attributes for a company entity. All fields are optional but improve matching quality.
      properties:
        domain:
          type: ["string", "null"]
          description: |
            Company website domain without protocol or trailing slash.

            The most reliable identifier — strongly recommended when available.
          example: newscatcherapi.com
        description:
          type: ["string", "null"]
          description: Detailed description of the company used for matching.
          example: Provider of news and web search APIs for developers
        key_persons:
          type: ["array", "null"]
          items:
            type: string
          description: |
            Names of key people associated with the company (founders, executives, etc.). Improves matching for articles that mention people rather than the company name.
          example:
            - Artem Bugara
            - Maksym Sugonyaka
        alternative_names:
          type: ["array", "null"]
          items:
            type: string
          description: |
            Alternative names, abbreviations, or aliases. Helps resolve common variations of the company name.
          example:
            - NC
            - NewsCatcher API

    AdditionalAttributes:
      type: object
      description: Additional attributes for the entity, keyed by entity type.
      properties:
        company_attributes:
          $ref: "#/components/schemas/CompanyAttributes"

    CreateEntityRequest:
      type: object
      required:
        - name
      description: |
        Request body for creating a single entity. Only `name` is required.
        The more fields you provide, the better the matching quality.
      properties:
        name:
          type: string
          minLength: 1
          description:
            The company or person name. Required and must be non-empty.
          example: NewsCatcher
        entity_type:
          $ref: "#/components/schemas/EntityType"
        description:
          type: string
          description: |
            Free-text description of the entity used for disambiguation when similar names exist.
          example: AI-powered news data provider
        additional_attributes:
          $ref: "#/components/schemas/AdditionalAttributes"

    UpdateEntityRequest:
      type: object
      description: |
        Request body for updating an entity. All fields are optional — only fields included in the request are updated. Fields not included are left unchanged.

        **Note**: When updating `additional_attributes.company_attributes`, the provided object replaces the existing company attributes in full. Include all attribute fields you want to retain.
      properties:
        name:
          type: string
          description: Updated entity name.
          example: NewsCatcher Inc.
        description:
          type: string
          description: Updated description.
          example: Updated description
        additional_attributes:
          $ref: "#/components/schemas/AdditionalAttributes"

    CreateEntityResponse:
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the created entity.
          example: "854198fa-f702-49db-a381-0427fa87f173"
        status:
          type: string
          description: |
            Initial status of the entity. Always `pending` immediately after creation — enrichment happens asynchronously.
          example: pending

    EntityResponse:
      type: object
      required:
        - id
        - entity_type
        - organization_id
        - name
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the entity.
          example: "854198fa-f702-49db-a381-0427fa87f173"
        entity_type:
          $ref: "#/components/schemas/EntityType"
        organization_id:
          type: string
          format: uuid
          description: Organization that owns this entity.
          example: "e5d9e9b0-e415-4941-8ef0-916c5ee56207"
        name:
          type: string
          description: Entity name.
          example: NewsCatcher
        description:
          type: ["string", "null"]
          description: Free-text description.
          example: AI-powered news data provider
        additional_attributes:
          $ref: "#/components/schemas/AdditionalAttributes"
        status:
          $ref: "#/components/schemas/EntityStatus"
        created_by_user_id:
          type: string
          format: uuid
          description: ID of the user who created this entity.
          example: "870e258e-12ec-4a47-8656-e7a43b0265b3"
        created_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp of when the entity was created. Returned without timezone offset (server-local time).
          example: "2026-04-08T15:21:17.272139"
        updated_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp of when the entity was last updated. Returned without timezone offset (server-local time).
          example: "2026-04-08T15:21:18.248316"

    CreateEntitiesBatchRequest:
      type: object
      required:
        - entities
      properties:
        entities:
          type: array
          items:
            $ref: "#/components/schemas/CreateEntityRequest"
          description: |
            Array of entities to create. Each item follows the same schema
            as single entity creation.
          minItems: 1

    CreateEntitiesBatchResponse:
      type: object
      required:
        - entities
        - count
      properties:
        entities:
          type: array
          items:
            $ref: "#/components/schemas/CreateEntityResponse"
          description: |
            Array of created entity stubs in the same order as the input.
        count:
          type: integer
          description: Total number of entities created.
          example: 3

    EntityListResponse:
      type: object
      required:
        - entities
        - total
        - page
        - page_size
      properties:
        entities:
          type: array
          items:
            $ref: "#/components/schemas/EntityResponse"
          description: Array of entity objects for this page.
        total:
          type: integer
          description: Total number of entities matching the filter criteria.
          example: 17
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of entities per page.
          example: 100

    EntitySummary:
      type: object
      required:
        - id
        - name
        - entity_type
        - status
      description: |
        Abbreviated entity object returned when listing entities within a
        dataset. Uses a flat `attributes` key rather than the nested
        `additional_attributes.company_attributes` structure used in
        standalone entity endpoints.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the entity.
          example: "854198fa-f702-49db-a381-0427fa87f173"
        name:
          type: string
          description: Entity name.
          example: NewsCatcher
        entity_type:
          $ref: "#/components/schemas/EntityType"
        status:
          $ref: "#/components/schemas/EntityStatus"
        description:
          type: ["string", "null"]
          description: Free-text description.
          example: AI-powered news data provider
        attributes:
          $ref: "#/components/schemas/CompanyAttributes"

    # ── Dataset request/response schemas ──────────────────────────────────────

    CreateDatasetRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          description: Name for the dataset.
          example: My Portfolio
        description:
          type: string
          description: Optional description.
          example: Companies in our investment portfolio
        entity_ids:
          type: array
          items:
            type: string
            format: uuid
          description: |
            IDs of existing entities to include in the dataset. All IDs must belong to the authenticated organization. If any ID is invalid or not found, the request fails with `400`.
          example:
            - "854198fa-f702-49db-a381-0427fa87f173"
            - "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

    UpdateDatasetRequest:
      type: object
      description: |
        Updates dataset name or description. At least one field should be
        provided.
      properties:
        name:
          type: string
          description: Updated dataset name.
          example: My Portfolio (updated)
        description:
          type: string
          description: Updated description.
          example: Updated description

    DatasetResponse:
      type: object
      required:
        - id
        - organization_id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the dataset.
          example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
        organization_id:
          type: string
          format: uuid
          description: Organization that owns this dataset.
          example: "e5d9e9b0-e415-4941-8ef0-916c5ee56207"
        name:
          type: string
          description: Dataset name.
          example: My Portfolio
        description:
          type: ["string", "null"]
          description: Optional description.
          example: Companies in our investment portfolio
        entity_count:
          type: integer
          description: Total number of entities in this dataset.
          default: 0
          example: 4
        latest_status:
          $ref: "#/components/schemas/DatasetStatus"
        created_by_user_id:
          type: string
          format: uuid
          description: ID of the user who created this dataset.
          example: "870e258e-12ec-4a47-8656-e7a43b0265b3"
        created_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp of when the dataset was created. Returned without timezone offset (server-local time).
          example: "2026-04-08T15:21:36.026993"
        updated_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp of when the dataset was last updated. Returned without timezone offset (server-local time).
          example: "2026-04-08T15:21:38.401148"

    DatasetListResponse:
      type: object
      required:
        - datasets
        - total
        - page
        - page_size
      properties:
        datasets:
          type: array
          items:
            $ref: "#/components/schemas/DatasetResponse"
          description: Array of dataset objects for this page.
        total:
          type: integer
          description: Total number of datasets matching the filter criteria.
          example: 5
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of datasets per page.
          example: 100

    ValidationReport:
      type: object
      required:
        - total_rows
        - valid_rows
        - skipped_count
        - skipped_rows
      description: Summary of CSV processing results.
      properties:
        total_rows:
          type: integer
          description: |
            Total number of data rows in the uploaded CSV (excluding the
            header row).
          example: 4
        valid_rows:
          type: integer
          description: Number of rows successfully processed into entities.
          example: 3
        skipped_count:
          type: integer
          description: Number of rows skipped due to validation errors.
          example: 1
        skipped_rows:
          type: array
          items:
            $ref: "#/components/schemas/SkippedRow"
          description: Details for each skipped row.

    SkippedRow:
      type: object
      required:
        - row
        - reason
      description: Details about a CSV row that was skipped during processing.
      properties:
        row:
          type: integer
          description: |
            1-based row number in the CSV file (including the header row).

            A value of `3` means the third line of the file (second data row).
          example: 3
        reason:
          type: string
          description: Human-readable explanation of why the row was skipped.
          example: "missing required field: name"

    CreateDatasetCsvResponse:
      type: object
      required:
        - dataset_id
        - dataset_name
        - entities_created
        - validation_report
      properties:
        dataset_id:
          type: string
          format: uuid
          description: Unique identifier of the created dataset.
          example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
        dataset_name:
          type: string
          description: Name of the created dataset.
          example: My Portfolio
        entities_created:
          type: integer
          description: Number of entities successfully created from the CSV.
          example: 3
        validation_report:
          $ref: "#/components/schemas/ValidationReport"

    UploadCsvToDatasetResponse:
      type: object
      required:
        - dataset_id
        - entities_created
        - validation_report
      properties:
        dataset_id:
          type: string
          format: uuid
          description: ID of the dataset that was updated.
          example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
        entities_created:
          type: integer
          description: Number of new entities created from the CSV.
          example: 3
        validation_report:
          $ref: "#/components/schemas/ValidationReport"

    DatasetEntityIdsRequest:
      type: object
      required:
        - entity_ids
      properties:
        entity_ids:
          type: array
          items:
            type: string
            format: uuid
          description: List of entity IDs to add or remove.
          minItems: 1
          example:
            - "854198fa-f702-49db-a381-0427fa87f173"

    ListDatasetEntitiesRequest:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          default: 1
          description: The page number to retrieve.
          example: 1
        page_size:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
          description: The number of entities per page.
          example: 100
        search:
          type: string
          description: Filters entities by name using a case-insensitive substring match.
          example: "OpenAI"
        status:
          $ref: "#/components/schemas/EntityStatus"
        entity_type:
          $ref: "#/components/schemas/EntityType"
        sort_by:
          $ref: "#/components/schemas/EntitySortBy"
        sort_order:
          $ref: "#/components/schemas/SortOrder"

    ManageEntitiesResponse:
      type: object
      required:
        - dataset_id
        - affected_count
      properties:
        dataset_id:
          type: string
          format: uuid
          description: ID of the dataset that was modified.
          example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
        affected_count:
          type: integer
          description: Number of entities that were added or removed.
          example: 1

    DatasetEntityListResponse:
      type: object
      required:
        - entities
        - total
        - page
        - page_size
      properties:
        entities:
          type: array
          items:
            $ref: "#/components/schemas/EntitySummary"
          description: Array of entity summary objects for this page.
        total:
          type: integer
          description: Total number of entities in the dataset.
          example: 4
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of entities per page.
          example: 100

    DatasetStatusHistoryResponse:
      type: object
      required:
        - dataset_id
        - history
      properties:
        dataset_id:
          type: string
          format: uuid
          description: ID of the dataset.
          example: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
        history:
          type: array
          items:
            $ref: "#/components/schemas/DatasetStatusEntry"
          description: Status change entries, ordered oldest to newest.

    DatasetStatusEntry:
      type: object
      required:
        - status
      description: A single status change event in a dataset's history.
      properties:
        status:
          $ref: "#/components/schemas/DatasetStatus"
        additional_information:
          type: ["object", "null"]
          description: Additional context about the status change, if available.
          example: null
        created_at:
          type: string
          format: date-time
          description: |
            ISO 8601 timestamp of when this status was set. Returned without timezone offset (server-local time).
          example: "2026-04-08T15:21:36.066271"

    # ── Company Watchlist output schema ──────────────────────────────────────────

    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 attributes exist in the database. 
            
            The field name matches the value of `type` — for example, `"company"` type entities have a `company`  field.

# ── Project schemas ───────────────────────────────────────────────────

    ProjectResourceType:
      type: string
      enum:
        - job
        - monitor
        - dataset
        - monitor_group
      description: |
        Resource type for project association.
    CreateProjectRequestDto:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          description: Name for the project.
          example: "AI M&A Tracking"
        description:
          type: string
          description: Optional description.
          example: "Tracks AI-related M&A activity for our investment team."

    UpdateProjectRequestDto:
      type: object
      description: Updates one or more fields of an existing project. At least one field must be provided.
      properties:
        name:
          type: string
          minLength: 1
          description: New name for the project.
          example: "AI M&A Tracking (Q2)"
        description:
          type: string
          description: New description for the project.
          example: "Updated scope to include private equity."

    AddResourceRequestDto:
      type: object
      required:
        - resources
      properties:
        resources:
          type: array
          minItems: 1
          description: Resources to assign to the project.
          items:
            $ref: "#/components/schemas/ResourceItemDto"

    ResourceItemDto:
      type: object
      required:
        - resource_type
        - resource_id
      properties:
        resource_type:
          $ref: "#/components/schemas/ProjectResourceType"
        resource_id:
          type: string
          format: uuid
          description: ID of the resource to add.
          example: "48421e16-1f50-4048-b62c-d3bc0789d30d"

    CreateProjectResponseDto:
      type: object
      required:
        - success
        - message
        - project_id
        - name
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Project created successfully."
        project_id:
          type: string
          format: uuid
          description: Project identifier.
          example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
        name:
          type: string
          description: Name of the created project.
          example: "AI M&A Tracking"

    ProjectResponseDto:
      type: object
      required:
        - success
        - message
        - project_id
        - name
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "OK"
        project_id:
          type: string
          format: uuid
          description: Project identifier.
          example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
        name:
          type: string
          description: Project name.
          example: "AI M&A Tracking"
        description:
          type: ["string", "null"]
          description: Project description.
          example: "Tracks AI-related M&A activity for our investment team."
        resources_count:
          type: integer
          description: Number of resources assigned to this project.
          example: 4
          default: 0
        created_at:
          type: string
          format: date-time
          description: Project creation timestamp.
          example: "2026-05-20T14:31:35Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update.
          example: "2026-05-20T14:31:35Z"

    UpdateProjectResponseDto:
      type: object
      required:
        - success
        - message
        - project_id
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Project updated successfully."
        project_id:
          type: string
          format: uuid
          description: Project identifier.
          example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"

    ProjectSummaryDto:
      type: object
      description: Abbreviated project object returned in list responses.
      required:
        - project_id
        - name
      properties:
        project_id:
          type: string
          format: uuid
          description: Project identifier.
          example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
        name:
          type: string
          description: Project name.
          example: "AI M&A Tracking"
        description:
          type: ["string", "null"]
          description: Project description.
          example: "Tracks AI-related M&A activity for our investment team."
        resources_count:
          type: integer
          description: Number of resources assigned to this project.
          example: 4
          default: 0
        created_at:
          type: string
          format: date-time
          description: Project creation timestamp.
          example: "2026-05-20T14:31:35Z"
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update.
          example: "2026-05-20T14:31:35Z"

    ProjectListResponseDto:
      type: object
      required:
        - total
        - page
        - page_size
        - total_pages
        - projects
      properties:
        total:
          type: integer
          description: Total number of projects matching the filter criteria.
          example: 2
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of projects per page.
          example: 100
        total_pages:
          type: integer
          description: Total number of pages.
          example: 1
        projects:
          type: array
          items:
            $ref: "#/components/schemas/ProjectSummaryDto"
          description: Projects on this page.

    ProjectOverviewCountsDto:
      type: object
      description: |
        Status breakdown for a single resource type.
      additionalProperties: true

    ProjectOverviewResponseDto:
      type: object
      required:
        - project_id
        - overview
      properties:
        project_id:
          type: string
          format: uuid
          description: Project identifier.
          example: "60a85db4-78ec-4b78-876a-bc7d9cdadd04"
        overview:
          type: object
          description: Resource counts grouped by type.
          required:
            - jobs
            - monitors
            - datasets
            - monitor_groups
          properties:
            jobs:
              $ref: "#/components/schemas/ProjectOverviewCountsDto"
            monitors:
              $ref: "#/components/schemas/ProjectOverviewCountsDto"
            datasets:
              $ref: "#/components/schemas/ProjectOverviewCountsDto"
            monitor_groups:
              $ref: "#/components/schemas/ProjectOverviewCountsDto"

    ProjectResourceDto:
      type: object
      description: A resource assigned to a project.
      required:
        - resource_type
        - resource_id
      properties:
        resource_type:
          $ref: "#/components/schemas/ProjectResourceType"
        resource_id:
          type: string
          format: uuid
          description: Resource identifier.
          example: "48421e16-1f50-4048-b62c-d3bc0789d30d"
        name:
          type: string
          description: |
            Resource display name. For jobs, this is the original query
            string. For monitors and datasets, this is the resource name.
          example: "Series B fintech funding rounds"
        created_at:
          type: string
          format: date-time
          description: Resource creation timestamp.
          example: "2026-05-20T14:31:37Z"
        metadata:
          type: object
          description: Additional resource-specific metadata.
          additionalProperties: true
          example: {}

    ProjectResourceListResponseDto:
      type: object
      required:
        - total
        - page
        - page_size
        - total_pages
        - resources
      properties:
        total:
          type: integer
          description: Total number of resources assigned to the project.
          example: 1
        page:
          type: integer
          description: Current page number.
          example: 1
        page_size:
          type: integer
          description: Number of resources per page.
          example: 100
        total_pages:
          type: integer
          description: Total number of pages.
          example: 1
        resources:
          type: array
          items:
            $ref: "#/components/schemas/ProjectResourceDto"
          description: Resources on this page.

    AddResourceResponseDto:
      type: object
      required:
        - success
        - message
        - results
      properties:
        success:
          type: boolean
          description: True if the overall operation succeeded.
          example: true
        message:
          type: string
          description: Top-level result message.
          example: "Resources added to project."
        results:
          type: array
          description: Per-resource outcome, one entry per submitted resource.
          items:
            $ref: "#/components/schemas/ResourceResultDto"

    ResourceResultDto:
      type: object
      required:
        - resource_type
        - resource_id
        - success
        - message
      properties:
        resource_type:
          type: string
          description: Type of the resource.
          example: "job"
        resource_id:
          type: string
          format: uuid
          description: Resource identifier.
          example: "48421e16-1f50-4048-b62c-d3bc0789d30d"
        success:
          type: boolean
          description: True if this resource was processed successfully.
          example: true
        message:
          type: string
          description: Per-resource result message.
          example: "Resource added to project."
        already_exists:
          type: boolean
          description: True if the resource is already assigned to this project.
          default: false
          example: false

    RemoveResourceResponseDto:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: True if the operation succeeded; false otherwise.
          example: true
        message:
          type: string
          description: Human-readable result message.
          example: "Resource removed from project."

    GetPlanLimitsResponseDto:
      type: object
      required:
        - features
      properties:
        features:
          type: array
          items:
            $ref: "#/components/schemas/PlanFeature"
          description: Plan features with current usage.

    PlanFeature:
      type: object
      required:
        - name
        - code
      properties:
        name:
          type: string
          description: Human-readable feature name.
          example: "Jobs Concurrency"
        code:
          type: string
          description: Machine-readable feature identifier.
          example: "Jobs_Concurrency"
        value_type:
          type: string
          description: Data type of the feature value.
          example: "integer"
        value:
          description: Feature limit. Type depends on `value_type`.
          example: 20
        current_usage:
          type: number
          description: Current usage count for this feature.
          example: 1

    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message.
          example: "Invalid API key"

    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

    ValidationErrorResponse:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: "#/components/schemas/ValidationErrorDetail"

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication.