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

# Ingest Document Version Handler

> Upload a new file for an existing document, creating a new version and triggering ingestion.

Creates a new document version (incrementing the highest version number),
uploads the file to S3, and starts the ingestion workflow. Upon successful
ingestion, the new version is automatically activated (set as the document's
active_version) and the old version's Qdrant points are deactivated.

Returns 201 with the Temporal workflow ID.



## OpenAPI

````yaml /openapi.yaml post /v1/documents/{document_id}/ingest
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/documents/{document_id}/ingest:
    post:
      tags:
        - documents
      summary: Ingest Document Version Handler
      description: >-
        Upload a new file for an existing document, creating a new version and
        triggering ingestion.


        Creates a new document version (incrementing the highest version
        number),

        uploads the file to S3, and starts the ingestion workflow. Upon
        successful

        ingestion, the new version is automatically activated (set as the
        document's

        active_version) and the old version's Qdrant points are deactivated.


        Returns 201 with the Temporal workflow ID.
      operationId: ingest_document_version
      parameters:
        - name: document_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: Document ID
            title: Document Id
          description: Document ID
        - 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:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_ingest_document_version'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestDocumentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_ingest_document_version:
      properties:
        file:
          type: string
          title: File
          format: binary
        ingestion_mode:
          $ref: '#/components/schemas/IngestionMode'
          nullable: true
          description: >-
            Ingestion pipeline mode: 'high_accuracy' (default for PDF),
            'standard' (default for DOCX/XLSX/PPTX/PLAINTEXT), or 'single_chunk'
            (default for IMAGE/CSV). Auto-resolved when omitted.
        chunk_type:
          $ref: '#/components/schemas/ChunkType'
          nullable: true
          description: >-
            Force chunk type (TABLE/IMAGE/HTML). Only valid with single_chunk
            mode.
        secondary_taxonomy:
          $ref: '#/components/schemas/ImageTaxonomy'
          nullable: true
          description: >-
            Force secondary taxonomy (e.g. 'picture', 'flowchart'). Only valid
            with single_chunk mode and chunk_type=IMAGE.
        page_dpi:
          type: integer
          maximum: 216
          minimum: 36
          title: Page Dpi
          description: DPI for PDF page screenshots (default 72, min 36, max 216).
          default: 72
      type: object
      required:
        - file
      title: Body_ingest_document_version
    IngestDocumentResponse:
      properties:
        workflow_id:
          type: string
          title: Workflow Id
          description: Temporal workflow ID
        document_id:
          type: string
          format: uuid
          title: Document Id
        document_version_id:
          type: string
          format: uuid
          title: Document Version Id
      additionalProperties: false
      type: object
      required:
        - workflow_id
        - document_id
        - document_version_id
      title: IngestDocumentResponse
      description: Response with workflow execution details.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    IngestionMode:
      type: string
      enum:
        - high_accuracy
        - standard
        - single_chunk
      title: IngestionMode
      description: Ingestion pipeline mode — determines conversion and chunking strategy.
    ChunkType:
      type: string
      enum:
        - TEXT
        - TABLE
        - IMAGE
        - HTML
        - UNKNOWN
      title: ChunkType
      description: Type of chunk content.
    ImageTaxonomy:
      type: string
      enum:
        - picture
        - flowchart
      title: ImageTaxonomy
      description: Image classification taxonomy with prompt descriptions.
    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

````