Dify Octri Demo
POST/datasets/{dataset_id}/documents/{document_id}/segments

Create document chunks

Creates one or more chunks within a document in a knowledge base. Provide at least one item in segments, and include non-empty content for each chunk; Q&A-mode documents also require answer. The response includes the created chunks and the document’s chunking mode.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 1 body field
dataset_idstringrequired
The UUID of the knowledge base containing the document.
document_idstringrequired
The UUID of the document in which to create chunks.

Chunk creation payload containing at least one chunk object.

segmentsarray<object>required
Array of chunk objects to create.

5 status codes
200Returns the created chunk objects and the document’s chunking mode.
dataarray<object>optional
List of created chunks.
doc_formstringoptional
Document chunking mode used by this document.
400Returned when a chunk field is invalid, an answer is missing for a Q&A-mode document, the request exceeds the per-request chunk limit, the embedding model is missing or misconfigured, or body validation fails.

2 documented failures

  • invalid_param

    Exceeded maximum segments limit of 1000.

    invalid_param (segments limit)

  • provider_not_initialize

    No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.

    provider_not_initialize

403Returned when dataset API access is disabled, subscription capacity or request limits are reached, the plan does not permit the operation, or the API key is not scoped to the knowledge base.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404Returned when the knowledge base or document does not exist, or the document is incomplete or disabled.

One documented failure

  • not_found

    Dataset not found.

    not_found

503Returned on the Dify Cloud Sandbox plan when vector-space usage cannot be verified.

One documented failure

  • service_unavailable

    Unable to verify vector space usage right now. Please try again later.

    service_unavailable

Error handling

A 400 is returned for invalid chunk fields, a missing answer in Q&A mode, too many chunks in one request, an unconfigured embedding model, or schema validation failures; a 403 is returned when access, subscription capacity, rate limits, or plan restrictions block the request. A 404 is returned when the knowledge base or document is missing, incomplete, or disabled; a 503 is returned when vector-space usage cannot be verified on the Cloud Sandbox plan. The dataset_id path parameter and document_id path parameter must be UUIDs. The segments array must contain at least one object, and each object must include non-empty content.