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

# Preview Knowledge Base Item Chunks

> Splits the start of the item's text with the settings you send and returns the chunks, without saving anything. Use it to compare settings before you regenerate the chunks. Text items use their content; file items need a first processing run to have finished. The `addContext` sentence is not added in previews.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/voice-agents/knowledge-base/{id}/chunks/preview
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/voice-agents/knowledge-base/{id}/chunks/preview:
    post:
      summary: Preview chunking settings
      description: >-
        Splits the start of the item's text with the settings you send and
        returns the chunks, without saving anything. Use it to compare settings
        before you regenerate the chunks. Text items use their content; file
        items need a first processing run to have finished. The `addContext`
        sentence is not added in previews.
      parameters:
        - in: path
          name: id
          required: true
          description: ID of the knowledge base item.
          schema:
            type: string
            format: uuid
            example: d949f13f-40d2-4e48-ac86-b66633070603
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chunkingConfig:
                  $ref: '#/components/schemas/KnowledgeBaseChunkingConfig'
                maxChars:
                  type: integer
                  minimum: 1000
                  maximum: 20000
                  default: 20000
                  description: >-
                    How many characters from the start of the text to preview
                    (1,000-20,000).
                  example: 20000
            examples:
              qa:
                summary: Try Q&A pairs
                value:
                  chunkingConfig:
                    strategy: QA_PAIRS
                    targetTokens: 300
                  maxChars: 20000
              saved:
                summary: Current settings
                value:
                  maxChars: 5000
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Chunks preview generated successfully!
                  messageKey:
                    type: string
                    example: ChunksPreviewGenerated
                  data:
                    type: object
                    properties:
                      chunks:
                        type: array
                        description: 'The preview chunks (not saved): at most the first 60.'
                        items:
                          type: object
                          properties:
                            position:
                              type: integer
                              example: 1
                            text:
                              type: string
                              example: |-
                                Q: How long do refunds take?
                                A: Refunds are issued within 5 business days.
                            metadata:
                              $ref: '#/components/schemas/KnowledgeBaseChunkMetadata'
                            flagged:
                              type: boolean
                              example: false
                      totalChunks:
                        type: integer
                        description: >-
                          Number of chunks the previewed text produced (can be
                          more than the 60 returned in `chunks`).
                        example: 42
                      truncated:
                        type: boolean
                        description: >-
                          `true` when the text was longer than `maxChars` or
                          more than 60 chunks were produced.
                        example: true
                      config:
                        type: object
                        additionalProperties: true
                        description: >-
                          The settings used (yours over the defaults), plus
                          `strategyApplied`, `contextApplied` (true when at
                          least one chunk got a generated context; always false
                          in previews), `overlapApplied`, `pages`,
                          `detectedLanguage` (`SEMANTIC` runs) and
                          `modelApplied` (`LLM_GUIDED` only).
                        example:
                          strategy: QA_PAIRS
                          targetTokens: 300
                          minTokens: 40
                          maxTokens: 1800
                          overlapTokens: 0
                          respectHeadings: true
                          keepAtomicBlocks: true
                          splitTables: true
                          addContext: false
                          strategyApplied: QA_PAIRS
                          contextApplied: false
                          overlapApplied: 0
                          pages: 1
                      strategyApplied:
                        type: string
                        enum:
                          - SEMANTIC
                          - BY_PARAGRAPH
                          - QA_PAIRS
                          - BY_PAGE
                          - FIXED
                          - LLM_GUIDED
                        description: >-
                          The method actually used (`BY_PARAGRAPH` after a
                          fallback).
                        example: QA_PAIRS
        '400':
          description: >-
            Invalid body, or the item has no text to preview yet
            (`KnowledgeBaseItemCannotBePreviewed`), or a `chunkingConfig` whose
            sizes contradict each other (`ChunkingMinTokensExceedsHalfTarget`,
            `ChunkingOverlapTokensExceedsHalfTarget`,
            `ChunkingMaxTokensBelowTarget`,
            `ChunkingMinTokensExceedsMaxTokens`), or `overlapTokens` above 0
            with `QA_PAIRS` (`ChunkingOverlapTokensNotAllowedForQaPairs`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            Your API key or role does not have the `knowledge_base:read`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Knowledge base item not found in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '503':
          description: >-
            Chunking failed: Hamsa couldn't chunk the item right now, or the
            text was refused (for example text under 50 characters). `message`
            says why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    KnowledgeBaseChunkingConfig:
      type: object
      properties:
        strategy:
          type: string
          enum:
            - SEMANTIC
            - BY_PARAGRAPH
            - QA_PAIRS
            - BY_PAGE
            - FIXED
            - LLM_GUIDED
          description: >-
            Chunking method: `SEMANTIC`: keeps a section that fits the target
            whole, otherwise splits it where the topic changes (default,
            slowest); `BY_PARAGRAPH`: groups paragraphs up to the target size
            without crossing headings; `LLM_GUIDED`: an AI model picks where
            each chunk starts, for text without headings or paragraphs;
            `QA_PAIRS`: one chunk per question and its answer; `BY_PAGE`: one
            chunk per page (files with pages); `FIXED`: equal pieces that end on
            sentence boundaries.
          default: SEMANTIC
          example: SEMANTIC
        targetTokens:
          type: integer
          minimum: 50
          maximum: 1500
          default: 400
          example: 400
          description: >-
            Size each chunk aims for, in tokens (50-1500). Agents read the first
            600 characters of each chunk, so 150-300 keeps a chunk whole: try
            150-250 for FAQs and 200-300 for manuals.
        minTokens:
          type: integer
          minimum: 0
          maximum: 500
          default: 40
          example: 40
          description: >-
            Smaller chunks are joined to a neighbour or flagged for review
            (0-500 tokens). At most half of `targetTokens` and not above
            `maxTokens`. Default 40, or half of `targetTokens` when that is
            smaller.
        maxTokens:
          type: integer
          minimum: 100
          maximum: 1800
          default: 1800
          example: 1800
          description: >-
            Hard limit: longer chunks are split at a sentence boundary (100-1800
            tokens). At least `targetTokens` (`ChunkingMaxTokensBelowTarget`).
        overlapTokens:
          type: integer
          minimum: 0
          maximum: 300
          description: >-
            Tokens repeated from the end of one chunk at the start of the next,
            so an idea that crosses the cut isn't lost (0-300, and at most half
            of `targetTokens`: `ChunkingOverlapTokensExceedsHalfTarget`). Every
            chunk takes one except the first, tables and Q&A pairs, across
            sections too. Must be `0` with `QA_PAIRS`
            (`ChunkingOverlapTokensNotAllowedForQaPairs`).
          default: 0
          example: 0
        respectHeadings:
          type: boolean
          default: true
          description: >-
            Never split across a heading, and start each chunk with the full
            path of headings it sits under.
        keepAtomicBlocks:
          type: boolean
          default: true
          description: Never cut lists, numbered steps or code blocks in the middle.
        splitTables:
          type: boolean
          description: >-
            Split large tables into groups of rows, each repeating the header
            row.
          default: true
        addContext:
          type: boolean
          description: >-
            Add a short sentence to each chunk saying where it sits in the
            document. Takes longer.
          default: false
      description: >-
        Chunking settings. Omitted values use the defaults. When a method can't
        be applied, the text is split by `BY_PARAGRAPH` instead (for example
        `QA_PAIRS` with no questions found, or `BY_PAGE` for text without
        pages). Values out of range or that contradict each other are refused
        with 400, never adjusted; when `targetTokens` is left out, the rules use
        400.
    KnowledgeBaseChunkMetadata:
      type: object
      nullable: true
      description: Details from the chunker. `null` for chunks you added yourself.
      properties:
        headerPath:
          type: string
          description: The headings the chunk sits under, outermost first.
          example: Pricing > Enterprise
        page:
          type: integer
          description: Page number (files with pages).
          example: 4
        kind:
          type: string
          enum:
            - prose
            - list
            - code
            - table
            - qa
          description: What the chunk contains.
          example: prose
        tokenCount:
          type: integer
          description: Size of the chunk text in tokens.
          example: 212
        qualityScore:
          type: number
          description: Chunker quality score, 0 to 1.
          example: 0.71
        strategy:
          type: string
          enum:
            - SEMANTIC
            - BY_PARAGRAPH
            - QA_PAIRS
            - BY_PAGE
            - FIXED
            - LLM_GUIDED
          description: >-
            The chunking method actually used (it can differ from the one you
            asked for after a fallback).
          example: SEMANTIC
        context:
          type: string
          description: The sentence added in front of the chunk when `addContext` is on.
          example: >-
            This section lists the support options included in the Enterprise
            plan.
        title:
          type: string
          description: Chunk title chosen by the AI model (`LLM_GUIDED` only).
          example: Enterprise support
        flags:
          type: array
          items:
            type: string
            enum:
              - low_quality
              - too_short
              - oversized
          description: Why the chunk is flagged for review.
          example:
            - too_short
        overlapApplied:
          type: boolean
          example: true
          description: >-
            Only when `overlapTokens` is above 0: whether the start of this
            chunk repeats the end of the chunk before it.
        overlapTokenCount:
          type: integer
          example: 38
          description: 'Only when `overlapApplied` is `true`: how many tokens were repeated.'
        overlapSkipReason:
          type: string
          enum:
            - first_chunk
            - table
            - qa_pair
            - after_table
            - after_qa_pair
            - qa_pairs_strategy
            - last_word_over_overlap
          example: first_chunk
          description: >-
            Only when `overlapApplied` is `false`: why. `first_chunk`: the first
            chunk of the item; `table`: the chunk is a table; `qa_pair`: the
            chunk is a question and its answer; `after_table`: the chunk before
            it is a table; `after_qa_pair`: the chunk before it is a question
            and its answer; `qa_pairs_strategy`: the item uses `QA_PAIRS`;
            `last_word_over_overlap`: the last word of the chunk before it is
            longer than `overlapTokens`.
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.