findall-openapi

openapi: 3.1.0
info:
  title: Parallel FindAll API
  version: 0.1.2
  description: |
    # FindAll API

    The FindAll API discovers and evaluates entities that match complex criteria from natural language objectives. Submit a high-level goal and the service automatically generates structured match conditions, discovers relevant candidates, and evaluates each against the criteria. Returns comprehensive results with detailed reasoning, citations, and confidence scores for each match decision.

    ## Core Concepts

    ### FindAll Lifecycle

    A FindAll run progresses through several statuses:

    1. **queued** - Run has been created and is waiting to start
    2. **action_required** - User input needed (e.g., schema review)
    3. **running** - Actively discovering and evaluating candidates
    4. **completed** - Successfully finished with all results available
    5. **failed** - Encountered an error during execution
    6. **cancelling** - Cancel request received, shutting down
    7. **cancelled** - Successfully cancelled by user

    **Active statuses**: queued, action_required, running, cancelling
    **Terminal statuses**: completed, failed, cancelled

    Termination reasons when in terminal status:
    - `low_match_rate` - Too few matches found relative to candidates evaluated
    - `match_limit_met` - Reached the specified match limit
    - `candidates_exhausted` - No more candidates to evaluate
    - `user_cancelled` - User requested cancellation
    - `error_occurred` - System error during execution
    - `timeout` - Run exceeded maximum allowed time

    ### FindAll Candidates

    Candidates represent entities being evaluated against match conditions. Each candidate has:

    - **candidate_id** - Unique identifier
    - **name** - Entity name
    - **url** - Context URL for disambiguation
    - **description** - Brief description (optional)
    - **match_status** - One of: generated, matched, unmatched, discarded
    - **output** - Structured results of match condition evaluations
    - **basis** - Citations, reasoning, and confidence for each field

    A candidate is considered a **match** only if ALL match conditions are satisfied.

    Match status progression:
    1. `generated` - Candidate discovered and queued for evaluation
    2. `matched` - All match conditions satisfied
    3. `unmatched` - One or more match conditions not satisfied
    4. `discarded` - Removed from evaluation (duplicate, invalid, etc.)

    ### Generator Pricing

    FindAll supports multiple generator tiers with different cost/quality tradeoffs:

    - **base** - Fast, economical for simple criteria
    - **core** - Balanced performance and accuracy (recommended)
    - **pro** - Higher accuracy for complex requirements
    - **preview** - Latest experimental features

    Costs vary by generator tier and number of candidates evaluated. See pricing documentation for details.

    ## Features

    ### Match Conditions

    Match conditions define what makes an entity a match. Each condition has:
    - **name** - Identifier for the condition
    - **description** - Detailed criteria (be specific for best results)

    Example:
    ```json
    {
      "name": "soc2_type_ii_certified",
      "description": "Company must have SOC2 Type II certification (not Type I). Look for evidence in: trust centers, security/compliance pages, audit reports, or press releases specifically mentioning 'SOC2 Type II'. If no explicit SOC2 Type II mention is found, consider requirement not satisfied."
    }
    ```

    ### Enrichment

    After initial matching, enrich candidates with additional structured data:

    - Define custom output schema for enrichment data
    - Specify processor tier (base, core, pro, preview)
    - Use MCP servers for specialized data sources
    - Enrichment runs on matched candidates only

    ### Extension

    Increase the match limit of an active run to find more matches:

    - Specify additional matches to find
    - New limit = current limit + additional matches
    - Only works on active runs
    - Useful when initial results are promising

    ### Cancellation

    Stop a FindAll run before completion:

    - Only works on active runs (not terminal statuses)
    - Run transitions to 'cancelling' then 'cancelled'
    - Partial results remain available
    - Termination reason set to 'user_cancelled'

    ### Real-time Updates (SSE)

    Stream events via Server-Sent Events for real-time progress:

    Event types:
    - `findall.schema.updated` - Schema modified (e.g., after ingest)
    - `findall.status` - Run status changed
    - `findall.candidate.generated` - New candidate discovered
    - `findall.candidate.matched` - Candidate matched all conditions
    - `findall.candidate.unmatched` - Candidate failed one or more conditions
    - `findall.candidate.discarded` - Candidate removed from evaluation
    - `findall.candidate.enriched` - Enrichment data added

    Resume from specific event using `last_event_id` parameter.

    ### Webhooks

    Receive HTTP notifications for run events:

    - Specify webhook URL and event types during run creation
    - Receive POST requests with event data
    - Useful for async workflows and integrations

    Supported event types: `task_run.status`

    ### Preview Features

    Access experimental capabilities via the `parallel-beta` header:

    - Schema auto-generation from natural language
    - Advanced matching algorithms
    - Specialized processors

    Features may change or be deprecated without notice.

    ## Migration Guide

    When migrating existing code:

    1. Update endpoint URLs to `/v1beta/findall/*`
    2. Replace task-based polling with SSE streaming
    3. Use structured match conditions instead of free-form objectives
    4. Leverage enrichment for additional data extraction
    5. Implement webhook handlers for production workflows

    ## Quick Start

    Basic workflow:

    1. **(Optional) Generate schema** - Use `/v1beta/findall/ingest` to convert natural language to structured schema
    2. **Create run** - POST to `/v1beta/findall/runs` with objective, entity_type, match_conditions, and generator
    3. **Monitor progress** - Stream events via `/v1beta/findall/runs/{id}/events` or poll status
    4. **Get results** - Retrieve snapshot via `/v1beta/findall/runs/{id}/result`
    5. **(Optional) Extend** - Add more matches if needed
    6. **(Optional) Enrich** - Add structured data to matches

    Example:
    ```json
    {
      "objective": "Find all AI companies that raised Series A funding in 2024",
      "entity_type": "companies",
      "match_conditions": [
        {
          "name": "developing_ai_products",
          "description": "Company must be developing artificial intelligence products"
        },
        {
          "name": "raised_series_a_2024",
          "description": "Company must have raised Series A funding in 2024"
        }
      ],
      "generator": "core",
      "match_limit": 50
    }
    ```
  contact:
    name: Parallel Support
    url: https://parallel.ai
    email: support@parallel.ai

servers:
  - url: https://api.parallel.ai
    description: Parallel API Production

security:
  - ApiKeyAuth: []

tags:
  - name: Schema Generation
    description: Convert natural language objectives to structured FindAll specifications
  - name: Run Management
    description: Create and monitor FindAll runs
  - name: Results
    description: Retrieve FindAll results and status
  - name: Extensions
    description: Modify active FindAll runs (extend, enrich, cancel)
  - name: Streaming
    description: Real-time event streams for FindAll runs

paths:
  /v1beta/findall/ingest:
    post:
      tags:
        - Schema Generation
      summary: Generate FindAll Schema
      description: |
        Transforms a natural language search objective into a structured FindAll specification.

        **Note**: This endpoint requires the `parallel-beta` header.

        The generated specification serves as a suggested starting point and can be further customized before creating a run.

        Use this to:
        - Convert free-form objectives to structured match conditions
        - Get suggested entity types and field definitions
        - Bootstrap FindAll runs with AI-generated schemas

        The output can be directly used as input to `POST /v1beta/findall/runs` or modified as needed.
      operationId: ingestFindAllRun
      parameters:
        - $ref: "#/components/parameters/ParallelBeta"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IngestInput"
      responses:
        "200":
          description: Successfully generated FindAll schema
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllSchema"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs:
    post:
      tags:
        - Run Management
      summary: Create FindAll Run
      description: |
        Starts a new FindAll run to discover and evaluate entities matching specified criteria.

        This endpoint immediately returns a FindAll run object with status 'queued'. The run will progress through various statuses as it executes.

        **Track Progress**:
        - Poll status: `GET /v1beta/findall/runs/{findall_id}`
        - Stream events: `GET /v1beta/findall/runs/{findall_id}/events` (recommended)
        - Webhooks: Specify webhook in request body

        **Get Results**:
        - Snapshot: `GET /v1beta/findall/runs/{findall_id}/result`

        **Match Limit**: Specifies maximum matches to find (5-1000). Run may terminate early if:
        - Match rate is too low (insufficient quality candidates)
        - All candidates exhausted
        - System timeout reached

        **Exclude List**: Optionally specify entities to exclude from results by name/URL.

        **Metadata**: Attach arbitrary key-value pairs for tracking and organization.
      operationId: createFindAllRun
      parameters:
        - $ref: "#/components/parameters/ParallelBeta"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FindAllRunInput"
      responses:
        "200":
          description: FindAll run created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllRun"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/TooManyRequests"

  /v1beta/findall/runs/{findall_id}:
    get:
      tags:
        - Results
      summary: Get FindAll Run Status
      description: |
        Retrieves current status and metadata for a FindAll run.

        Use this to:
        - Check run progress (status, metrics)
        - Determine if run is still active
        - Get termination reason for completed runs

        For detailed results including candidates, use `GET /v1beta/findall/runs/{findall_id}/result` instead.

        For real-time updates, use `GET /v1beta/findall/runs/{findall_id}/events` (SSE streaming).
      operationId: getFindAllRun
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      responses:
        "200":
          description: FindAll run status retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllRun"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/result:
    get:
      tags:
        - Results
      summary: Get FindAll Run Result
      description: |
        Retrieves a complete snapshot of FindAll run results at the time of request.

        Returns:
        - Run metadata and status
        - All evaluated candidates with match status
        - Output data and reasoning for each candidate
        - Last event ID (for resuming event streams)

        This is a point-in-time snapshot. For active runs, results will continue to update. Use the `last_event_id` from the response to resume streaming from this point.

        **Result Structure**:
        - `run` - Current run status and metadata
        - `candidates` - Array of all evaluated candidates
        - `last_event_id` - ID of most recent event (for SSE resumption)

        Candidates include full details: output data, citations, reasoning, and confidence scores.
      operationId: getFindAllResult
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      responses:
        "200":
          description: FindAll result snapshot retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllRunResult"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/schema:
    get:
      tags:
        - Results
      summary: Get FindAll Run Schema
      description: |
        Retrieves the schema definition for a FindAll run.

        Returns:
        - Objective (natural language goal)
        - Entity type
        - Match conditions with descriptions
        - Enrichment configurations (if any)
        - Generator tier
        - Match limit

        Useful for:
        - Understanding run configuration
        - Debugging match conditions
        - Replicating runs with modifications
      operationId: getFindAllSchema
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      responses:
        "200":
          description: FindAll schema retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllSchema"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/events:
    get:
      tags:
        - Streaming
      summary: Stream FindAll Events (SSE)
      description: |
        Opens a Server-Sent Events (SSE) stream for real-time FindAll run updates.

        **Event Types**:
        - `findall.schema.updated` - Schema modified (e.g., after ingest)
        - `findall.status` - Run status changed
        - `findall.candidate.generated` - New candidate discovered
        - `findall.candidate.matched` - Candidate matched all conditions
        - `findall.candidate.unmatched` - Candidate failed conditions
        - `findall.candidate.discarded` - Candidate removed from evaluation
        - `findall.candidate.enriched` - Enrichment data added

        **Resumption**: Use `last_event_id` parameter to resume from a specific point. Get this ID from:
        - Previous event stream disconnect
        - Result snapshot (`GET /v1beta/findall/runs/{id}/result`)

        **Timeout**: Optional timeout in seconds. If not specified, connection stays open while run is active. If set, stream closes after specified duration.

        **Best Practices**:
        - Implement reconnection logic with exponential backoff
        - Store last_event_id to resume from disconnects
        - Handle all event types gracefully
        - Close connection when run reaches terminal status
      operationId: streamFindAllEvents
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - name: last_event_id
          in: query
          required: false
          description: Event ID to resume streaming from (for reconnection)
          schema:
            type: string
            nullable: true
        - name: timeout
          in: query
          required: false
          description: Timeout in seconds. If not set, keeps connection alive while run is active
          schema:
            type: number
            nullable: true
        - $ref: "#/components/parameters/ParallelBeta"
      responses:
        "200":
          description: Event stream opened successfully
          content:
            text/event-stream:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/FindAllSchemaUpdatedEvent"
                  - $ref: "#/components/schemas/FindAllRunStatusEvent"
                  - $ref: "#/components/schemas/FindAllCandidateEvent"
                  - $ref: "#/components/schemas/ErrorEvent"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/extend:
    post:
      tags:
        - Extensions
      summary: Extend FindAll Run
      description: |
        Increases the match limit of an active FindAll run to find more matches.

        **When to Use**:
        - Initial results are promising and you want more
        - Original match_limit was too conservative
        - Business needs changed during run execution

        **Requirements**:
        - Run must be in active status (queued, action_required, running)
        - Additional match limit must be > 0

        **Behavior**:
        - New limit = current limit + additional_match_limit
        - Run continues from current state
        - Does not restart evaluation

        **Example**: If original limit was 50 and you extend by 25, new limit is 75.

        **Note**: Extension does not guarantee finding additional matches. Run may still terminate early if candidates are exhausted or match rate is too low.
      operationId: extendFindAllRun
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FindAllExtendInput"
      responses:
        "200":
          description: FindAll run extended successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllSchema"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/enrich:
    post:
      tags:
        - Extensions
      summary: Add Enrichment to FindAll Run
      description: |
        Adds structured data enrichment to matched candidates in a FindAll run.

        **Use Cases**:
        - Extract additional fields from matched entities
        - Get company financials, tech stack, team size, etc.
        - Integrate with external data sources via MCP servers

        **Enrichment Flow**:
        1. Define output schema (JSON Schema format)
        2. Select processor tier (base, core, pro, preview)
        3. Optionally configure MCP servers for specialized tools
        4. Enrichment runs on matched candidates only

        **Output Schema**: Specify the structure of enrichment data using JSON Schema. Only a subset of JSON Schema is supported (see examples).

        **MCP Servers**: Configure Model Context Protocol servers for accessing external APIs, databases, or specialized tools during enrichment.

        **Processor Selection**:
        - base: Fast, economical
        - core: Balanced (recommended)
        - pro: Higher accuracy
        - preview: Experimental features

        **Note**: Enrichment is applied to candidates that have matched all conditions. Unmatched candidates are not enriched.
      operationId: enrichFindAllRun
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FindAllEnrichInput"
      responses:
        "200":
          description: Enrichment added successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FindAllSchema"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"

  /v1beta/findall/runs/{findall_id}/cancel:
    post:
      tags:
        - Extensions
      summary: Cancel FindAll Run
      description: |
        Cancels an active FindAll run before completion.

        **Requirements**:
        - Run must be in active status (queued, action_required, running, cancelling)
        - Cannot cancel terminal runs (completed, failed, cancelled)

        **Behavior**:
        - Run transitions to 'cancelling' status immediately
        - Current work completes gracefully
        - Status changes to 'cancelled' when shutdown complete
        - Termination reason set to 'user_cancelled'

        **Partial Results**: All candidates evaluated before cancellation remain available via the result endpoint.

        **Use Cases**:
        - Accidentally started wrong run
        - Results no longer needed
        - Want to modify parameters and restart
        - Cost control
      operationId: cancelFindAllRun
      parameters:
        - $ref: "#/components/parameters/FindAllId"
        - $ref: "#/components/parameters/ParallelBeta"
      responses:
        "200":
          description: FindAll run cancellation initiated
          content:
            application/json:
              schema:
                type: object
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Cannot cancel a terminated FindAll run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "422":
          $ref: "#/components/responses/ValidationError"

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        API key for authentication. Get your API key from the Parallel dashboard.

        Include in all requests as: `x-api-key: YOUR_API_KEY`

  parameters:
    FindAllId:
      name: findall_id
      in: path
      required: true
      description: Unique identifier for the FindAll run
      schema:
        type: string

    ParallelBeta:
      name: parallel-beta
      in: header
      required: false
      description: |
        Optional header to enable beta features.

        Comma-separated list of beta features to enable.
        Some endpoints require this header for access.
      schema:
        type: string
        nullable: true

  schemas:
    IngestInput:
      type: object
      required:
        - objective
      properties:
        objective:
          type: string
          description: |
            Natural language objective to convert into a FindAll run specification.

            Be specific and include all requirements. The AI will generate:
            - Suggested entity type
            - Structured match conditions
            - Field definitions
          example: Find all AI companies that raised Series A funding in 2024

    FindAllRunInput:
      type: object
      required:
        - objective
        - entity_type
        - match_conditions
        - generator
        - match_limit
      properties:
        objective:
          type: string
          description: Natural language objective describing what to find
          example: Find all AI companies that raised Series A funding in 2024
        entity_type:
          type: string
          description: |
            Type of entity being searched for (e.g., companies, people, products, events).

            Should be a plural noun that describes the category of entities.
        match_conditions:
          type: array
          items:
            $ref: "#/components/schemas/MatchCondition"
          description: |
            List of conditions that must ALL be satisfied for an entity to match.

            Each condition should be atomic and specific. Use detailed descriptions for best results.
        generator:
          type: string
          enum: [base, core, pro, preview]
          description: |
            Generator tier to use for the FindAll run.

            - base: Fast, economical for simple criteria
            - core: Balanced performance and accuracy (recommended)
            - pro: Higher accuracy for complex requirements
            - preview: Latest experimental features
        match_limit:
          type: integer
          minimum: 5
          maximum: 1000
          description: |
            Maximum number of matches to find.

            Run may terminate early if:
            - Match rate too low
            - Candidates exhausted
            - System timeout
        exclude_list:
          type: array
          items:
            $ref: "#/components/schemas/ExcludeCandidate"
          nullable: true
          description: |
            Optional list of entities to exclude from results.

            Specify by name and/or URL. Useful for filtering out known entities or duplicates.
        metadata:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
          nullable: true
          description: |
            Optional metadata key-value pairs for tracking and organization.

            Stored with run and returned in all status/result queries.
        webhook:
          $ref: "#/components/schemas/Webhook"
          nullable: true
          description: Optional webhook configuration for event notifications

    FindAllExtendInput:
      type: object
      required:
        - additional_match_limit
      properties:
        additional_match_limit:
          type: integer
          minimum: 1
          description: |
            Number of additional matches to find.

            This value is added to the current match limit.
            Example: Current limit 50 + additional 25 = new limit 75

    FindAllEnrichInput:
      type: object
      required:
        - output_schema
      properties:
        processor:
          type: string
          default: core
          description: Processor tier to use for enrichment (base, core, pro, preview)
        output_schema:
          $ref: "#/components/schemas/JsonSchema"
          description: |
            JSON Schema defining the structure of enrichment data to extract.

            Only a subset of JSON Schema is supported. See examples for details.
        mcp_servers:
          type: array
          items:
            $ref: "#/components/schemas/McpServer"
          nullable: true
          description: |
            Optional list of Model Context Protocol servers for specialized tools.

            Use MCP servers to access external APIs, databases, or custom tools during enrichment.

    MatchCondition:
      type: object
      required:
        - name
        - description
      properties:
        name:
          type: string
          description: Identifier for this match condition (used in output fields)
        description:
          type: string
          description: |
            Detailed description of what must be true for this condition to be satisfied.

            **Be specific**: Include details about what evidence to look for, where to find it, and how to interpret it.

            **Good practices**:
            - Specify exact terms or certifications
            - List acceptable sources of evidence
            - Define edge cases and how to handle them
            - Include what constitutes insufficient evidence
          example: |
            Company must have SOC2 Type II certification (not Type I). Look for evidence in: trust centers, security/compliance pages, audit reports, or press releases specifically mentioning 'SOC2 Type II'. If no explicit SOC2 Type II mention is found, consider requirement not satisfied.

    ExcludeCandidate:
      type: object
      required:
        - name
        - url
      properties:
        name:
          type: string
          description: Name of the entity to exclude
        url:
          type: string
          description: URL of the entity to exclude

    Webhook:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: URL to receive webhook POST requests
        event_types:
          type: array
          items:
            type: string
            enum: [task_run.status]
          default: []
          description: |
            Event types to send webhook notifications for.

            Currently supported: task_run.status

    JsonSchema:
      type: object
      required:
        - json_schema
      properties:
        json_schema:
          type: object
          additionalProperties: true
          description: |
            JSON Schema object defining output structure.

            Only a subset of JSON Schema is supported:
            - type: string, number, integer, boolean, object, array
            - properties: object with property definitions
            - required: array of required property names
            - description: field descriptions
            - additionalProperties: typically false

            Not supported: $ref, allOf, anyOf, oneOf, complex validation rules
          example:
            type: object
            additionalProperties: false
            required: [ceo_name, employee_count]
            properties:
              ceo_name:
                type: string
                description: Name of the current CEO
              employee_count:
                type: integer
                description: Approximate number of full-time employees
        type:
          type: string
          const: json
          default: json
          description: Schema type (always "json")

    McpServer:
      type: object
      required:
        - url
        - name
      properties:
        type:
          type: string
          const: url
          default: url
          description: Type of MCP server (always "url")
        url:
          type: string
          format: uri
          description: URL of the MCP server endpoint
        headers:
          type: object
          additionalProperties:
            type: string
            format: password
            writeOnly: true
          nullable: true
          description: Optional HTTP headers for MCP server requests
        name:
          type: string
          description: Name identifier for this MCP server
        allowed_tools:
          type: array
          items:
            type: string
          nullable: true
          description: |
            Optional list of allowed tools from this server.

            If not specified, all tools are allowed.

    FindAllSchema:
      type: object
      required:
        - objective
        - entity_type
        - match_conditions
      properties:
        objective:
          type: string
          description: Natural language objective of the FindAll run
          example: Find all AI companies that raised Series A funding in 2024
        entity_type:
          type: string
          description: Type of entity being searched for
        match_conditions:
          type: array
          items:
            $ref: "#/components/schemas/MatchCondition"
          description: List of conditions that must all be satisfied
        enrichments:
          type: array
          items:
            $ref: "#/components/schemas/FindAllEnrichInput"
          nullable: true
          description: List of enrichment configurations (if any)
        generator:
          type: string
          enum: [base, core, pro, preview]
          default: core
          description: Generator tier used for this run
        match_limit:
          type: integer
          nullable: true
          description: Maximum number of matches to find

    FindAllRun:
      type: object
      required:
        - findall_id
        - status
        - generator
      properties:
        findall_id:
          type: string
          description: Unique identifier for this FindAll run
        status:
          $ref: "#/components/schemas/FindAllRunStatus"
        generator:
          type: string
          enum: [base, core, pro, preview]
          description: Generator tier used for this run
        metadata:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
          nullable: true
          description: User-provided metadata
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when run was created (RFC 3339 format)
        modified_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp of last result modification (RFC 3339 format)

    FindAllRunStatus:
      type: object
      required:
        - status
        - is_active
        - metrics
      properties:
        status:
          type: string
          enum:
            [
              queued,
              action_required,
              running,
              completed,
              failed,
              cancelling,
              cancelled,
            ]
          description: |
            Current status of the FindAll run.

            Active: queued, action_required, running, cancelling
            Terminal: completed, failed, cancelled
        is_active:
          type: boolean
          description: True if run is in an active (non-terminal) status
        metrics:
          $ref: "#/components/schemas/FindAllCandidateMetrics"
        termination_reason:
          type: string
          enum:
            [
              low_match_rate,
              match_limit_met,
              candidates_exhausted,
              user_cancelled,
              error_occurred,
              timeout,
            ]
          nullable: true
          description: |
            Reason for termination (only set when status is terminal).

            - low_match_rate: Too few matches relative to candidates evaluated
            - match_limit_met: Reached specified match limit
            - candidates_exhausted: No more candidates available
            - user_cancelled: User requested cancellation
            - error_occurred: System error during execution
            - timeout: Run exceeded maximum allowed time

    FindAllCandidateMetrics:
      type: object
      properties:
        generated_candidates_count:
          type: integer
          default: 0
          description: Number of candidates discovered and queued for evaluation
        matched_candidates_count:
          type: integer
          default: 0
          description: Number of candidates that matched all conditions

    FindAllRunResult:
      type: object
      required:
        - run
        - candidates
      properties:
        run:
          $ref: "#/components/schemas/FindAllRun"
          description: Current run status and metadata
        candidates:
          type: array
          items:
            $ref: "#/components/schemas/FindAllCandidate"
          description: All evaluated candidates at time of snapshot
        last_event_id:
          type: string
          nullable: true
          description: |
            ID of the most recent event at time of snapshot.

            Use this to resume event streaming from this point.

    FindAllCandidate:
      type: object
      required:
        - candidate_id
        - name
        - url
        - match_status
      properties:
        candidate_id:
          type: string
          description: Unique identifier for this candidate
        name:
          type: string
          description: Entity name
        url:
          type: string
          format: uri
          description: URL providing context for entity disambiguation
        description:
          type: string
          nullable: true
          description: Brief description of the entity
        match_status:
          type: string
          enum: [generated, matched, unmatched, discarded]
          description: |
            Current match status:
            - generated: Discovered, queued for evaluation
            - matched: Satisfied all match conditions
            - unmatched: Failed one or more conditions
            - discarded: Removed from evaluation
        output:
          type: object
          additionalProperties: true
          nullable: true
          description: |
            Structured results of match condition evaluations.

            Contains field values determined during evaluation. A candidate is a match only if ALL match conditions are satisfied.
        basis:
          type: array
          items:
            $ref: "#/components/schemas/FieldBasis"
          nullable: true
          description: Citations, reasoning, and confidence for each output field

    FieldBasis:
      type: object
      required:
        - field
        - reasoning
      properties:
        field:
          type: string
          description: Name of the output field this basis supports
        citations:
          type: array
          items:
            $ref: "#/components/schemas/Citation"
          default: []
          description: Sources supporting this field's value
        reasoning:
          type: string
          description: Explanation of how the value was determined
        confidence:
          type: string
          nullable: true
          description: |
            Confidence level (low, medium, high).

            Only certain processors provide confidence levels.
          example: high

    Citation:
      type: object
      required:
        - url
      properties:
        title:
          type: string
          nullable: true
          description: Title of the cited source
        url:
          type: string
          format: uri
          description: URL of the cited source
        excerpts:
          type: array
          items:
            type: string
          nullable: true
          description: |
            Relevant excerpts from the source.

            Only certain processors provide excerpts.

    # Event schemas for SSE
    FindAllSchemaUpdatedEvent:
      type: object
      required:
        - type
        - timestamp
        - event_id
        - data
      properties:
        type:
          type: string
          const: findall.schema.updated
        timestamp:
          type: string
          format: date-time
          description: When the event occurred
        event_id:
          type: string
          description: Unique event identifier for resumption
        data:
          $ref: "#/components/schemas/FindAllSchema"
          description: Updated schema

    FindAllRunStatusEvent:
      type: object
      required:
        - type
        - timestamp
        - event_id
        - data
      properties:
        type:
          type: string
          const: findall.status
        timestamp:
          type: string
          format: date-time
        event_id:
          type: string
        data:
          $ref: "#/components/schemas/FindAllRun"
          description: Updated run status

    FindAllCandidateEvent:
      type: object
      required:
        - type
        - timestamp
        - event_id
        - data
      properties:
        type:
          type: string
          enum:
            [
              findall.candidate.generated,
              findall.candidate.matched,
              findall.candidate.unmatched,
              findall.candidate.discarded,
              findall.candidate.enriched,
            ]
          description: |
            Type of candidate event:
            - generated: New candidate discovered
            - matched: Candidate matched all conditions
            - unmatched: Candidate failed one or more conditions
            - discarded: Candidate removed from evaluation
            - enriched: Enrichment data added
        timestamp:
          type: string
          format: date-time
        event_id:
          type: string
        data:
          $ref: "#/components/schemas/FindAllCandidate"
          description: Candidate with updated status

    ErrorEvent:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          const: error
        error:
          $ref: "#/components/schemas/Error"

    # Error schemas
    Error:
      type: object
      required:
        - ref_id
        - message
      properties:
        ref_id:
          type: string
          description: Reference ID for error tracking
        message:
          type: string
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: true
          nullable: true
          description: Optional additional error details

    ErrorResponse:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          const: error
        error:
          $ref: "#/components/schemas/Error"

    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: "#/components/schemas/ValidationError"

    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      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

  responses:
    NotFound:
      description: FindAll run not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

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

    UnprocessableEntity:
      description: Unprocessable content - request validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    PaymentRequired:
      description: Payment required - insufficient credit in account
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    TooManyRequests:
      description: Too many requests - quota temporarily exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"