Create Child Chunk
Create a child chunk under a parent chunk. Intended for documents that use the parent-child (
hierarchical_model) chunking mode.1 min read
post/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks
Request example
curl --request POST \
--url https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"content": "<string>"
}'import requests
url = "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
}
payload = {
"content": "<string>"
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.text)const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks', {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"content": "<string>"
})
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => '{
"content": "<string>"
}',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"
payload := strings.NewReader("{\n \"content\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"content\": \"<string>\"\n}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
"content": "<string>"
}'
response = http.request(request)
puts response.read_bodyResponse
{
"data": {
"content": "Dify is an open-source platform.",
"created_at": 1741267200,
"id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a",
"position": 1,
"segment_id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"type": "customized",
"updated_at": 1741267200,
"word_count": 6
}
}{
"code": "invalid_param",
"message": "Vector store operation failed: [Errno 111] Connection refused",
"status": 400
}{
"code": "provider_not_initialize",
"message": "No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.",
"status": 400
}{
"code": "forbidden",
"message": "Dataset api access is not enabled.",
"status": 403
}{
"code": "forbidden",
"message": "The capacity of the vector space has reached the limit of your subscription.",
"status": 403
}{
"code": "forbidden",
"message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
"status": 403
}{
"code": "forbidden",
"message": "To unlock this feature and elevate your Dify experience, please upgrade to a paid plan.",
"status": 403
}{
"code": "forbidden",
"message": "The API key is not authorized to access this knowledge base.",
"status": 403
}{
"code": "not_found",
"message": "Dataset not found.",
"status": 404
}{
"code": "not_found",
"message": "Document not found.",
"status": 404
}{
"code": "not_found",
"message": "Segment not found.",
"status": 404
}{
"code": "service_unavailable",
"message": "Unable to verify vector space usage right now. Please try again later.",
"status": 503
}post/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks
Authorization
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path parameters
Knowledge base ID, from List Knowledge Bases. For a scoped key, copy the ID from the Dify URL.
Document ID. Obtain it from List Documents.
Parent chunk ID. Obtain it from List Chunks.
Body
application/jsonChild chunk text content.
Responses
application/json
Child chunk created successfully.
Show child attributesHide child attributes
Text content of the child chunk.
Creation timestamp (Unix epoch in seconds).
Unique identifier of the child chunk.
Position of the child chunk within the parent chunk.
ID of the parent chunk this child chunk belongs to.
How the child chunk was created. Child chunks created or updated through the API are always
customized. System-generated child chunks are automatic.Last update timestamp (Unix epoch in seconds).
Word count of the child chunk content.