> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knowledgestack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Chunks Handler

> Search over chunks using dense vector, BM25 full-text, or hybrid retrieval.

Combines search with path-based authorization and optional metadata filters.
Uses Qdrant for retrieval and hydrates the matched chunks from Postgres.



## OpenAPI

````yaml /openapi.yaml post /v1/chunks/search
openapi: 3.1.0
info:
  title: Knowledge Stack API
  description: Knowledge Stack backend API for authentication and knowledge management
  version: 0.1.0
servers:
  - url: http://localhost:8000
    description: Knowledge Stack API local dev server
security: []
tags:
  - name: auth
    description: Authentication and identity management
  - name: users
    description: User accounts
  - name: tenants
    description: Tenant management
  - name: invites
    description: Tenant invitations
  - name: folders
    description: Folder management
  - name: documents
    description: Document management
  - name: document-versions
    description: Document version management
  - name: sections
    description: Document sections
  - name: chunks
    description: Chunk CRUD and semantic search
  - name: chunk-lineages
    description: Chunk lineage tracking
  - name: tags
    description: Tag management
  - name: path-parts
    description: Path part traversal and tagging
  - name: Threads
    description: Thread conversations
  - name: Thread Messages
    description: Thread message management
  - name: user-permissions
    description: User path permissions
  - name: workflows
    description: Ingestion workflows
paths:
  /v1/chunks/search:
    post:
      tags:
        - chunks
      summary: Search Chunks Handler
      description: >-
        Search over chunks using dense vector, BM25 full-text, or hybrid
        retrieval.


        Combines search with path-based authorization and optional metadata
        filters.

        Uses Qdrant for retrieval and hydrates the matched chunks from Postgres.
      operationId: search_chunks
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            type: string
            nullable: true
            title: Authorization
        - name: ks_uat
          in: cookie
          required: false
          schema:
            type: string
            nullable: true
            title: Ks Uat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChunkSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScoredChunkResponse'
                title: Response Search Chunks
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChunkSearchRequest:
      properties:
        query:
          type: string
          minLength: 1
          title: Query
          description: Search query text
        search_type:
          $ref: '#/components/schemas/SearchType'
          description: >-
            Search type: dense_only (semantic) or full_text (BM25 keyword), or
            hybrid (weighted dense+BM25)
          default: dense_only
        hybrid_profile:
          $ref: '#/components/schemas/HybridSearchProfile'
          description: 'Hybrid weighting preset: hybrid, dense, or sparse'
          default: hybrid
        dense_weight:
          type: number
          nullable: true
          title: Dense Weight
          description: >-
            Optional explicit weight for the dense branch. Must be provided
            together with sparse_weight and overrides hybrid_profile.
        sparse_weight:
          type: number
          nullable: true
          title: Sparse Weight
          description: >-
            Optional explicit weight for the sparse branch. Must be provided
            together with dense_weight and overrides hybrid_profile.
        parent_path_ids:
          items:
            type: string
            format: uuid
          type: array
          nullable: true
          title: Parent Path Ids
          description: >-
            Path part IDs to search within (non-CHUNK types). Defaults to
            tenant's /shared.
        tag_ids:
          items:
            type: string
            format: uuid
          type: array
          nullable: true
          title: Tag Ids
          description: Filter by tag IDs (AND logic — chunks must have ALL specified tags)
        chunk_types:
          items:
            $ref: '#/components/schemas/ChunkType'
          type: array
          minItems: 1
          nullable: true
          title: Chunk Types
          description: >-
            Filter by chunk types (TEXT, TABLE, IMAGE, HTML, UNKNOWN). Only
            chunks matching one of the listed types are returned.
        ingestion_time_after:
          type: string
          format: date-time
          nullable: true
          title: Ingestion Time After
          description: Only chunks ingested after this timestamp
        active_version_only:
          type: boolean
          title: Active Version Only
          description: Only return chunks from the active document version
          default: true
        top_k:
          type: integer
          maximum: 50
          minimum: 1
          title: Top K
          description: Number of results (1-50)
          default: 5
        score_threshold:
          type: number
          title: Score Threshold
          description: Minimum similarity score
          default: 0.3
        with_document:
          type: boolean
          title: With Document
          description: Include ancestor document_id and document_version_id in each result
          default: false
      additionalProperties: false
      type: object
      required:
        - query
      title: ChunkSearchRequest
      description: Request body for chunk search (dense vector, full-text BM25, or hybrid).
    ScoredChunkResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Chunk ID
        path_part_id:
          type: string
          format: uuid
          title: Path Part Id
          description: PathPart ID
        content_id:
          type: string
          format: uuid
          title: Content Id
          description: ChunkContent ID
        content:
          type: string
          title: Content
          description: Chunk text content
        chunk_type:
          $ref: '#/components/schemas/ChunkType'
          description: Type of chunk content
        chunk_metadata:
          $ref: '#/components/schemas/ChunkMetadata-Output'
          description: Chunk metadata
        num_tokens:
          type: integer
          nullable: true
          title: Num Tokens
          description: Number of tokens in chunk content
        parent_path_id:
          type: string
          format: uuid
          title: Parent Path Id
          description: Parent PathPart ID
        prev_sibling_path_id:
          type: string
          format: uuid
          nullable: true
          title: Prev Sibling Path Id
          description: Previous sibling PathPart ID
        next_sibling_path_id:
          type: string
          format: uuid
          nullable: true
          title: Next Sibling Path Id
          description: Next sibling PathPart ID
        materialized_path:
          type: string
          title: Materialized Path
          description: Full materialized path from root
        system_managed:
          type: boolean
          title: System Managed
          description: Whether this chunk is system-managed
        tenant_id:
          type: string
          format: uuid
          title: Tenant Id
          description: Tenant ID
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
        asset_s3_urls:
          items:
            type: string
          type: array
          title: Asset S3 Urls
          description: >-
            Presigned URLs to download the chunk's visual assets (6-hour
            validity)
        document:
          $ref: '#/components/schemas/ChunkDocumentResponse'
          nullable: true
          description: Ancestor document info (populated when with_document=true)
        document_version:
          $ref: '#/components/schemas/ChunkDocumentVersionResponse'
          nullable: true
          description: Ancestor document version info (populated when with_document=true)
        score:
          type: number
          title: Score
          description: Search ranking score returned by Qdrant
      additionalProperties: false
      type: object
      required:
        - id
        - path_part_id
        - content_id
        - content
        - chunk_type
        - chunk_metadata
        - parent_path_id
        - materialized_path
        - system_managed
        - tenant_id
        - created_at
        - updated_at
        - score
      title: ScoredChunkResponse
      description: Chunk response with search ranking score.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SearchType:
      type: string
      enum:
        - dense_only
        - full_text
        - hybrid
      title: SearchType
      description: Search type for chunk search.
    HybridSearchProfile:
      type: string
      enum:
        - hybrid
        - dense
        - sparse
      title: HybridSearchProfile
      description: Supported hybrid search weighting presets.
    ChunkType:
      type: string
      enum:
        - TEXT
        - TABLE
        - IMAGE
        - HTML
        - UNKNOWN
      title: ChunkType
      description: Type of chunk content.
    ChunkMetadata-Output:
      properties:
        polygons:
          items:
            $ref: '#/components/schemas/PolygonReference'
          type: array
          title: Polygons
          description: >-
            List of bounding boxes in the source document for the chunk,
            potentially from multiple areas of multiple pages.
        s3_urls:
          items:
            type: string
          type: array
          title: S3 Urls
          description: >-
            Ordered s3:// URIs to visual assets for this chunk. Single-element
            for standard IMAGE/TABLE/HTML chunks, multi-element for multi-page
            single-chunk ingestion.
        summary:
          type: string
          nullable: true
          title: Summary
          description: >-
            LLM-generated summary of the chunk content. Used for TABLE and HTML
            chunks to enrich embedding text.
        extracted_text_s3_uri:
          type: string
          nullable: true
          title: Extracted Text S3 Uri
          description: >-
            S3 URI to extracted PDF text used for LLM grounding during
            enrichment
        secondary_taxonomy:
          $ref: '#/components/schemas/ImageTaxonomy'
          nullable: true
          description: >-
            Sub-classification within a primary chunk type. For IMAGE chunks:
            'flowchart' (Mermaid extraction) or 'picture' (image description).
            None when not applicable. Will expand to cover TABLE sub-types in
            the future.
        sheet_name:
          type: string
          nullable: true
          title: Sheet Name
          description: Worksheet name this chunk was extracted from (XLSX only)
        block_type:
          type: string
          nullable: true
          title: Block Type
          description: XLSXParser block type (e.g. table, calculation_block, chart_anchor)
        source_uri:
          type: string
          nullable: true
          title: Source Uri
          description: Cell range URI reference in the source workbook (XLSX only)
        enriched_html:
          type: string
          nullable: true
          title: Enriched Html
          description: >-
            Rendered HTML for non-table XLSX chunks (tables use render_html as
            content)
        cell_range:
          type: string
          nullable: true
          title: Cell Range
          description: Cell address range, e.g. 'A1:D10' (XLSX only)
        dependency_summary:
          additionalProperties: true
          type: object
          nullable: true
          title: Dependency Summary
          description: >-
            Upstream/downstream/cross-sheet cell references for audit reasoning
            (XLSX only)
        formulas:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          nullable: true
          title: Formulas
          description: >-
            Formula cells in this chunk as [{address, formula, value}] (XLSX
            only)
        key_cells:
          items:
            additionalProperties: true
            type: object
          type: array
          nullable: true
          title: Key Cells
          description: Notable output/header cells for quick identification (XLSX only)
        named_ranges:
          items:
            additionalProperties: true
            type: object
          type: array
          nullable: true
          title: Named Ranges
          description: Named ranges overlapping this chunk (XLSX only)
      type: object
      title: ChunkMetadata
      description: Metadata for a chunk including source document references.
    ChunkDocumentResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Document ID
        name:
          type: string
          title: Name
          description: Document name
        document_type:
          $ref: '#/components/schemas/DocumentType'
          description: Document type (PDF, MARKDOWN, etc.)
        document_origin:
          $ref: '#/components/schemas/DocumentOrigin'
          description: Document origin (SOURCE, GENERATED, etc.)
      additionalProperties: false
      type: object
      required:
        - id
        - name
        - document_type
        - document_origin
      title: ChunkDocumentResponse
      description: Lightweight document info attached to a chunk response.
    ChunkDocumentVersionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: DocumentVersion ID
        version:
          type: integer
          title: Version
          description: Version number
        name:
          type: string
          title: Name
          description: Version path name (e.g. v0)
      additionalProperties: false
      type: object
      required:
        - id
        - version
        - name
      title: ChunkDocumentVersionResponse
      description: Lightweight document version info attached to a chunk response.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PolygonReference:
      properties:
        page:
          type: integer
          title: Page
          description: The page number of the source document where the polygon is located.
        polygon:
          $ref: '#/components/schemas/Polygon'
          description: The bounding box of the polygon.
      type: object
      required:
        - page
        - polygon
      title: PolygonReference
      description: Reference to a polygon on a specific page.
    ImageTaxonomy:
      type: string
      enum:
        - picture
        - flowchart
      title: ImageTaxonomy
      description: Image classification taxonomy with prompt descriptions.
    DocumentType:
      type: string
      enum:
        - PDF
        - DOCX
        - PLAINTEXT
        - IMAGE
        - XLSX
        - CSV
        - PPTX
        - UNKNOWN
      title: DocumentType
      description: Type of document.
    DocumentOrigin:
      type: string
      enum:
        - SOURCE
        - GENERATED
      title: DocumentOrigin
      description: Origin of document - source/purpose (all origins are first-class).
    Polygon:
      properties:
        x:
          type: integer
          title: X
          description: The x-coordinate of the top-left corner of the bounding box.
        'y':
          type: integer
          title: 'Y'
          description: The y-coordinate of the top-left corner of the bounding box.
        width:
          type: integer
          title: Width
          description: The width of the bounding box.
        height:
          type: integer
          title: Height
          description: The height of the bounding box.
      type: object
      required:
        - x
        - 'y'
        - width
        - height
      title: Polygon
      description: Bounding box polygon.

````