---
title: "Preview datasource chunks"
method: POST
path: "/v2/knowledge/{knowledge_id}/datasources/preview-chunks"
tags: ["Knowledge Bases"]
---

# Preview datasource chunks

`POST /v2/knowledge/{knowledge_id}/datasources/preview-chunks`

Parses an uploaded file and returns the chunks it would produce for the given chunking options without creating a datasource.

## Path parameters

- `knowledge_id` string, required

## Request body

- DatasourcesServicePreviewChunksRequest
  - `file_id` string, required
  - `chunking_options` DatasourceChunkingOptions
    - `chunking_configuration` union — The chunking configuration settings for the datasource. Defaults to the system's standard chunking configuration if not specified.
      - object — Optimized chunking strategy focusing on speed and avoiding duplication of content chunks. Deprecated: use one of the named chunking strategies instead.
        - `type` 'default', required
      - object — Provides advanced settings for customizing chunking behavior, enabling fine-grained control to better meet specific data processing needs. Deprecated: use one of the named chunking strategies instead.
        - `type` 'advanced', required
        - `chunk_max_characters` number — Defines the absolute maximum character length per chunk. Text elements exceeding this size will be automatically split into multiple chunks.
        - `chunk_overlap` number — Specifies the number of characters to overlap between consecutive chunks. This overlap helps maintain semantic continuity when splitting large text elements.
      - object — Splits text into fixed-size token windows with optional overlap. Predictable chunk sizes, no regard for sentence or paragraph boundaries.
        - `type` 'token', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `chunk_overlap` integer — Number of tokens to overlap between consecutive chunks. Helps preserve continuity across chunk boundaries.
      - object — Groups whole sentences up to the chunk size, so chunks never cut a sentence in half.
        - `type` 'sentence', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `chunk_overlap` integer — Number of tokens to overlap between consecutive chunks. Helps preserve continuity across chunk boundaries.
        - `min_sentences_per_chunk` integer — Minimum number of sentences each chunk must contain.
      - object — Splits on a separator hierarchy, falling back through paragraph, line, sentence, and word boundaries until chunks fit. Respects document structure.
        - `type` 'recursive', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `separators` string[] — Separator hierarchy to split on, tried in order. Defaults to paragraph, line, space, then character.
        - `min_characters_per_chunk` integer — Minimum number of characters each chunk must contain.
      - object — Splits on delimiters or a regular expression without tokenizing. Fastest option; chunk sizes vary with where delimiters fall.
        - `type` 'fast', required
        - `target_size` integer — Target chunk size in bytes.
        - `delimiters` string — Single-byte characters to split on.
        - `pattern` string — Multi-byte split pattern. Takes precedence over delimiters when set.
        - `prefix` boolean — Attach the delimiter to the start of the next chunk instead of the end of the previous one.
        - `consecutive` boolean — Split at the start of a run of consecutive delimiters rather than at each one.
        - `forward_fallback` boolean — Search forward for a delimiter when searching backward finds none.
      - object — Embeds the text and breaks where meaning shifts, so related passages stay together. Makes paid embedding calls.
        - `type` 'semantic', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `embedding_model` string — Embedding model used to detect semantic boundaries.
        - `dimensions` integer — Number of dimensions for the embedding output, when the model supports it.
        - `threshold` string — Similarity threshold from 0 through 1, or "auto".
        - `mode` 'window' | 'sentence' — Comparison mode.
        - `similarity_window` integer — Window size for similarity comparison.
      - object — Embeds the document before splitting it recursively, so each chunk is embedded with the surrounding document in context. Makes paid embedding calls.
        - `type` 'late', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `separators` string[] — Separator hierarchy to split on, tried in order. Defaults to paragraph, line, space, then character.
        - `min_characters_per_chunk` integer — Minimum number of characters each chunk must contain.
        - `embedding_model` string — Embedding model used to embed the document before it is split.
        - `dimensions` integer — Number of dimensions for the embedding output, when the model supports it.
      - object — Asks a model to choose the boundaries. Slowest and most expensive, best on documents with irregular structure. Makes paid model calls.
        - `type` 'agentic', required
        - `chunk_size` integer — Maximum number of tokens per chunk.
        - `model` string — Model that chooses the chunk boundaries.
        - `candidate_size` integer — Size of candidate splits offered to the model.
        - `min_characters_per_chunk` integer — Minimum number of characters each chunk must contain.
        - `system_prompt` string — Custom system prompt for the boundary model.
    - `chunking_cleanup_options` ChunkingCleanupOptions
      - `delete_emails` boolean
      - `delete_credit_cards` boolean
      - `delete_phone_numbers` boolean
      - `clean_bullet_points` boolean
      - `clean_numbered_list` boolean
      - `clean_unicode` boolean
      - `clean_dashes` boolean
      - `clean_whitespaces` boolean

## Response `200`

Datasource chunk preview successfully generated

- DatasourcesServicePreviewChunksResponse
  - `chunks` PreviewChunk[], required
    - `text` string, required
    - `page_number` integer
  - `metadata` PreviewChunksMetadata, required
    - `words_count` integer, required
    - `sentences_count` integer, required
    - `paragraphs_count` integer, required
    - `tokens_count` integer, required
    - `characters_count` integer, required
    - `chunks_count` integer, required

## Changes

> 257 revisions in range; 71 not diffed.

- **2026-09-01** `359a7831a2f0` — 1 info
  - endpoint added
- **2026-09-01** `66b8a4902911` — 1 breaking
  - api path removed without deprecation
- **2026-09-01** `081200e02fe0` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/knowledge/:knowledge_id/datasources/preview-chunks/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/359a7831a2f0/schema)