Newscatcher Meta API

openapi: 3.2.0
info:
  title: NewsCatcher CatchAll Meta 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.\n\n### Authentication\n\nAll endpoints except /health and /version require `x-api-key` header. If the key is invalid or missing, the API returns the `403 Forbidden` error.\n\n### Job workflow\n\n1. (Optional) Get suggestions via /catchAll/initialize\n2. Submit a query via /catchAll/submit with optional date ranges and custom validators/enrichments\n3. Poll /catchAll/status/{job_id} until completed (10-15 minutes)\n4. Retrieve results via /catchAll/pull/{job_id}\n\n### Monitor workflow\n\n1. Create successful job via /catchAll/submit\n2. Create monitor via /catchAll/monitors/create with schedule\n3. Retrieve aggregated results via /catchAll/monitors/pull/{monitor_id}\n\n### Webhook workflow\n\n1. Create a webhook via `POST /catchAll/webhooks`\n2. Attach it to a job or monitor via `POST /catchAll/webhooks/{webhook_id}/resources`,\n   or pass `webhook_ids` at job or monitor creation time\n3. Receive HTTP notifications at the configured URL when each job completes\n\n### Company search workflow\n\n1. Create a dataset via `POST /catchAll/datasets/` or `POST /catchAll/datasets/upload`\n2. Wait for the dataset `latest_status` to reach `ready`\n3. Submit a job with `connected_dataset_ids` pointing to your dataset\n4. Retrieve results — each record includes a `connected_entities` array\n   with relevance scores per matched company\n\n### Important notes\n\n**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.\n"
  contact:
    name: NewsCatcher
    url: https://newscatcherapi.com
    email: support@newscatcherapi.com
servers:
- url: https://catchall.newscatcherapi.com
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Meta
  description: Operations to check API health and version.
paths:
  /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:
  responses:
    HealthCheckResponse:
      description: API is healthy
      content:
        application/json:
          schema:
            type: object
            properties:
              healthy:
                type: boolean
                example: true
    ForbiddenError:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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
  schemas:
    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
    GetPlanLimitsResponseDto:
      type: object
      required:
      - features
      properties:
        features:
          type: array
          items:
            $ref: '#/components/schemas/PlanFeature'
          description: Plan features with current usage.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication.
externalDocs:
  description: Find out more about NewsCatcher CatchAll API
  url: https://www.newscatcherapi.com/docs/web-search-api/get-started/introduction