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

# Ingest documents

> Bulk-load Q&A rows into one knowledge base from a CSV upload (the document plane; the singular `/knowledge-base` path). Admins only (`knowledge_base:write`). The CSV header must be exactly `question,response`; `mode=replace` (default) overwrites the KB's rows while `mode=append` adds to them. Scope `knowledge_base:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /knowledge-base/ingest
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /knowledge-base/ingest:
    post:
      tags:
        - Knowledge Base
      summary: Ingest documents
      description: >-
        Bulk-load Q&A rows into one knowledge base from a CSV upload (the
        document plane; the singular `/knowledge-base` path). Admins only
        (`knowledge_base:write`). The CSV header must be exactly
        `question,response`; `mode=replace` (default) overwrites the KB's rows
        while `mode=append` adds to them. Scope `knowledge_base:write`.
      operationId: ingest_knowledge_base_ca_api_v0_knowledge_base_ingest_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - knowledge_base_id
              properties:
                file:
                  type: string
                  format: binary
                  description: >-
                    UTF-8 CSV upload (a UTF-8 BOM is tolerated). Header row must
                    be exactly `question,response`, with at least one data row
                    and no extra columns; max 5 MB.
                knowledge_base_id:
                  type: string
                  description: >-
                    Target knowledge base id. Required (a 400 is returned if
                    absent) and must reference an existing KB in the caller's
                    workspace (else 404).
                mode:
                  type: string
                  enum:
                    - replace
                    - append
                  default: replace
                  description: >-
                    `replace` overwrites the KB's existing rows; `append` adds
                    to them.
      responses:
        '201':
          description: >-
            Rows ingested. `ingested` is the number of Q&A rows written, echoing
            the effective `mode` and target `knowledge_base_id`.
          content:
            application/json:
              example:
                ingested: 12
                mode: replace
                knowledge_base_id: kb_01jq8x9m2h4z7c0r5v3b8t6n1e
        '400':
          description: >-
            mode is not replace/append, knowledge_base_id is missing, the file
            exceeds 5 MB or is not UTF-8, or the CSV fails validation (empty,
            missing header, header not exactly `question,response`, extra
            columns, or a row missing question/response).
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: 'CSV header must be exactly: question,response'
        '401':
          description: No valid authentication was supplied.
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Authentication required
        '403':
          description: The caller lacks `knowledge_base:write` (admin-tier).
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: Scope 'knowledge_base:write' is required
        '404':
          description: The target knowledge base does not exist in the caller's workspace.
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: Knowledge base not found
        '500':
          description: Unexpected server error.
          content:
            application/json:
              example:
                error:
                  code: internal_error
                  message: An unexpected error occurred
        '503':
          description: No vector store is configured, so ingestion is unavailable.
          content:
            application/json:
              example:
                error:
                  code: service_unavailable
                  message: Knowledge base service is not configured
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````