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

# Create vector database ingestion job

> Start a new ingestion job to add files to a vector database.

Submit file IDs and chunking configuration to start a vector database ingestion job. The system converts files, generates embeddings, and indexes them in the specified database.

The response includes a `file_records` array with per-file tracking. Each record contains the file's status, timestamps for each state transition, and error diagnostics if a failure occurs.

Ingestion also captures source tracing metadata for every chunk — line numbers, character offsets, heading hierarchy, and source page number — stored alongside the embedding. This enables full provenance tracing from model output back to the original uploaded file via the chunk endpoint.

For job states, error codes, and SDK examples, see [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion). To get started with vector databases, see [Create and populate a vector database](https://docs.seekr.com/docs/create-and-populate-a-vector-database-sdk).


## OpenAPI

````yaml post /v1/flow/vectordb/{database_id}/ingestion
openapi: 3.1.0
info:
  title: SeekrFlow API
  description: SeekrFlow API Documentation
  termsOfService: http://www.seekr.com/support
  contact:
    name: Seekr API Support
    url: http://www.seekr.com/contact
    email: contact@seekr.com
  version: 5.99.0
servers:
  - url: https://flow.seekr.com
    description: SeekrBuild server base URL
security: []
paths:
  /v1/flow/vectordb/{database_id}/ingestion:
    post:
      tags:
        - Vector database
      summary: Create vector database ingestion job
      description: Start a new ingestion job to add files to a vector database.
      operationId: >-
        create_vector_database_ingestion_job_v1_flow_vectordb__database_id__ingestion_post
      parameters:
        - name: database_id
          in: path
          required: true
          schema:
            type: string
            title: Database Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VectorDatabaseIngestionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VectorDatabaseIngestionResponse'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    VectorDatabaseIngestionRequest:
      properties:
        file_ids:
          items:
            type: string
          type: array
          title: File Ids
          description: List of file ids to use for alignment
        method:
          anyOf:
            - type: string
            - type: 'null'
          title: Method
          description: >-
            Document extraction strategy used to convert raw files into clean
            markdown before chunking. `accuracy-optimized` (default) — runs the
            full Seekr extraction pipeline: tries up to 12 conversion methods in
            priority order (bookmark-aware hybrid extraction, Seekr-SaaS OCR,
            LLM post-processing, PyMuPDF, and more) with no word-count
            restrictions, selecting the highest-quality result for each
            document. Best for complex PDFs, tables, and documents where
            retrieval accuracy matters. `speed-optimized` — uses the same
            pipeline but skips methods that exceed per-method word-count
            thresholds, dramatically reducing processing time on large documents
            while still producing high-quality output.
          default: accuracy-optimized
          examples:
            - accuracy-optimized
            - speed-optimized
        chunking_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Chunking Method
          description: >-
            Strategy used to split the extracted markdown into chunks before
            embedding. `markdown` (default) — parses the heading hierarchy
            (`#`–`######`) to identify section boundaries, groups subsections
            into token-bounded chunks, and intelligently handles tables by
            repeating table headers across continuation chunks so every chunk is
            self-contained. Best for structured documents (reports, policies,
            manuals). `semantic` — uses spaCy sentence detection, generates
            paragraph-level embeddings, then applies Ward hierarchical
            clustering to group paragraphs by meaning rather than position.
            Produces topically coherent chunks even in poorly structured
            documents — ideal for improving answer quality on complex
            question-answering workloads. `sliding` — fixed-size overlapping
            windows with no structural awareness. Fast and predictable; best for
            plain-text or homogeneous content where document structure is
            absent.
          default: markdown
          examples:
            - markdown
            - semantic
            - sliding
        token_count:
          type: integer
          title: Token Count
          description: Target maximum tokens per chunk.
          default: 800
        overlap_tokens:
          type: integer
          title: Overlap Tokens
          description: >-
            Number of tokens repeated at the start of each chunk from the end of
            the previous one, preserving context across chunk boundaries.
          default: 100
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Optional flat JSON object attached to every chunk produced by this
            ingestion job. Constraints: (1) must be a flat object — no nested
            objects or arrays; (2) values must be string, number, boolean, or
            datetime (null is rejected); (3) maximum 20 fields; (4) string
            values are trimmed of leading/trailing whitespace and newlines are
            replaced with spaces. Example: {"year": 2024, "doc_type": "policy",
            "is_confidential": false}
          examples:
            - doc_type: policy
              is_confidential: false
              year: 2024
      type: object
      required:
        - file_ids
      title: VectorDatabaseIngestionRequest
    VectorDatabaseIngestionResponse:
      properties:
        id:
          type: string
          title: Id
        vector_database_id:
          type: string
          title: Vector Database Id
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        file_ids:
          items:
            type: string
          type: array
          title: File Ids
        metaflow_run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Metaflow Run Id
        file_records:
          anyOf:
            - items:
                $ref: '#/components/schemas/VectorDatabaseFileResponse'
              type: array
            - type: 'null'
          title: File Records
      type: object
      required:
        - id
        - vector_database_id
        - status
        - created_at
        - updated_at
        - error_message
        - file_ids
        - metaflow_run_id
      title: VectorDatabaseIngestionResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VectorDatabaseFileResponse:
      properties:
        id:
          type: string
          title: Id
        record_id:
          type: string
          title: Record Id
        vector_database_id:
          type: string
          title: Vector Database Id
        filename:
          type: string
          title: Filename
        method:
          anyOf:
            - type: string
            - type: 'null'
          title: Method
        chunk_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Chunk Method
        token_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Token Count
        overlap_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Overlap Tokens
        created_at:
          type: string
          format: date-time
          title: Created At
        ingestion_job_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Ingestion Job Id
        status:
          type: string
          title: Status
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        suggested_fix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Fix
        processing_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Processing At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
        failed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Failed At
        file_size_in_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: File Size In Bytes
        queue_position:
          anyOf:
            - type: integer
            - type: 'null'
          title: Queue Position
          description: Position in queue if status is queued
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            User-defined metadata associated with this file's chunks. Set at
            ingestion time or updated via PATCH
            /vectordb/{database_id}/metadata.
      type: object
      required:
        - id
        - record_id
        - vector_database_id
        - filename
        - created_at
        - status
      title: VectorDatabaseFileResponse
      description: Response model for a vector database file
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: >-
        Your Seekr API key, sent in the Authorization header with no 'Bearer'
        prefix.
      in: header
      name: Authorization

````