Dify Chunks API
Operations for managing document chunks and child chunks. 9 operation(s) from the Dify Service API.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dify-chunks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dify Chunks API
description: REST API for Dify applications and knowledge bases. Application endpoints authenticate
with an app API key; knowledge endpoints authenticate with a dataset API key.
version: 1.0.0
servers:
- url: https://{api_base_url}
description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own
API base URL.
variables:
api_base_url:
default: api.dify.ai/v1
description: Host and path of the API base URL, without the `https://` prefix.
security:
- ApiKeyAuth: []
tags:
- name: Chunks
description: Operations for managing document chunks and child chunks.
paths:
/datasets/{dataset_id}/documents/{document_id}/segments:
post:
tags:
- Chunks
summary: Create Chunks
description: Create one or more chunks within a document.
operationId: createSegments
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- segments
properties:
segments:
type: array
items:
type: object
properties:
content:
type: string
description: Chunk text content.
minLength: 1
answer:
type: string
description: Answer text. Required for Q&A-mode (`qa_model`) documents.
keywords:
type: array
items:
type: string
description: Keywords for the chunk.
attachment_ids:
type: array
items:
type: string
description: Attachment file IDs.
required:
- content
description: Array of chunk objects to create.
minItems: 1
responses:
'200':
description: Chunks created successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: List of created chunks.
items:
$ref: '#/components/schemas/Segment'
doc_form:
type: string
description: Document chunking mode used by this document.
examples:
success:
summary: Response Example
value:
data:
- id: f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1
position: 1
document_id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
content: Dify is an open-source LLM app development platform.
sign_content: ''
answer: ''
word_count: 9
tokens: 12
keywords:
- dify
- platform
- llm
index_node_id: a1b2c3d4-e5f6-7890-abcd-000000000001
index_node_hash: abc123def456
hit_count: 0
enabled: true
disabled_at: null
disabled_by: null
status: completed
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
updated_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
indexing_at: 1741267200
completed_at: 1741267200
error: null
stopped_at: null
child_chunks: []
attachments: []
summary: null
doc_form: text_model
'400':
description: '- `provider_not_initialize` : The knowledge base uses high-quality indexing but
its embedding model is missing or misconfigured.
- `invalid_param` : A chunk field is invalid (for example, `answer` is required for Q&A-mode
documents) or the number of chunks exceeds the per-request limit.
- Request-body schema validation (such as empty `content`) returns a non-standard body `{"error":
"<validation details>"}` with no `code` or `status` field.'
content:
application/json:
examples:
provider_not_initialize:
summary: provider_not_initialize
value:
status: 400
code: provider_not_initialize
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
invalid_param_limit:
summary: invalid_param (segments limit)
value:
status: 400
code: invalid_param
message: Exceeded maximum segments limit of 1000.
validation_error:
summary: schema validation (non-standard body)
value:
error: "1 validation error for SegmentCreatePayload\nsegments.0.content\n String\
\ should have at least 1 character [type=string_too_short, input_value='', input_type=str]"
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : The capacity of the vector space has reached the limit of your subscription.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.
- `forbidden` : To unlock this feature and elevate your Dify experience, please upgrade to
a paid plan.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (vector space)
value:
status: 403
code: forbidden
message: The capacity of the vector space has reached the limit of your subscription.
forbidden_3:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
forbidden_4:
summary: forbidden (upgrade plan)
value:
status: 403
code: forbidden
message: To unlock this feature and elevate your Dify experience, please upgrade to
a paid plan.
'404':
description: '- `not_found` : Dataset not found.
- `not_found` : Document not found.
- `not_found` : Document is not completed.
- `not_found` : Document is disabled.'
content:
application/json:
examples:
not_found_1:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found
value:
status: 404
code: not_found
message: Document not found.
not_found_3:
summary: not_found
value:
status: 404
code: not_found
message: Document is not completed.
not_found_4:
summary: not_found
value:
status: 404
code: not_found
message: Document is disabled.
'503':
description: '`service_unavailable` : Vector space usage could not be verified. Returned on
the Dify Cloud Sandbox plan only; retry the request later.'
content:
application/json:
examples:
service_unavailable:
summary: service_unavailable
value:
status: 503
code: service_unavailable
message: Unable to verify vector space usage right now. Please try again later.
x-mint:
href: /en/api-reference/chunks/create-chunks
metadata:
title: Create Chunks
sidebarTitle: Create Chunks
get:
tags:
- Chunks
summary: List Chunks
description: Returns a paginated list of chunks within a document, optionally filtered by keyword
or indexing status.
operationId: listSegments
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).
- name: page
in: query
schema:
type: integer
default: 1
minimum: 1
description: Page number.
- name: limit
in: query
schema:
type: integer
default: 20
minimum: 1
description: Number of items per page. Server caps at `100`.
- name: status
in: query
schema:
type: array
items:
type: string
style: form
explode: true
description: Filter chunks by indexing status, e.g. `completed`, `indexing`, `error`.
- name: keyword
in: query
schema:
type: string
description: Search keyword.
responses:
'200':
description: List of chunks.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: List of chunks.
items:
$ref: '#/components/schemas/Segment'
doc_form:
type: string
description: Document chunking mode used by this document.
total:
type: integer
description: Total number of matching chunks.
has_more:
type: boolean
description: Whether more items exist on the next page.
limit:
type: integer
description: Number of items per page.
page:
type: integer
description: Current page number.
examples:
success:
summary: Response Example
value:
data:
- id: f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1
position: 1
document_id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
content: Dify is an open-source LLM app development platform.
sign_content: ''
answer: ''
word_count: 9
tokens: 12
keywords:
- dify
- platform
- llm
index_node_id: a1b2c3d4-e5f6-7890-abcd-000000000001
index_node_hash: abc123def456
hit_count: 0
enabled: true
disabled_at: null
disabled_by: null
status: completed
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
updated_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
indexing_at: 1741267200
completed_at: 1741267200
error: null
stopped_at: null
child_chunks: []
attachments: []
summary: null
doc_form: text_model
total: 1
has_more: false
limit: 20
page: 1
'400':
description: '`provider_not_initialize` : The knowledge base uses high-quality indexing but
its embedding model is missing or misconfigured.'
content:
application/json:
examples:
provider_not_initialize:
summary: provider_not_initialize
value:
status: 400
code: provider_not_initialize
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
'403':
description: '`forbidden` : Dataset api access is not enabled.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '- `not_found` : Dataset not found.
- `not_found` : Document not found.'
content:
application/json:
examples:
not_found_1:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found
value:
status: 404
code: not_found
message: Document not found.
x-mint:
href: /en/api-reference/chunks/list-chunks
metadata:
title: List Chunks
sidebarTitle: List Chunks
/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}:
get:
tags:
- Chunks
summary: Get Chunk
description: Retrieve the full details of a single chunk.
operationId: getSegmentDetail
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).
- name: segment_id
in: path
required: true
schema:
type: string
format: uuid
description: Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).
responses:
'200':
description: Chunk details.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Segment'
doc_form:
type: string
description: Document chunking mode used by this document.
examples:
success:
summary: Response Example
value:
data:
id: f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1
position: 1
document_id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
content: Dify is an open-source LLM app development platform.
sign_content: ''
answer: ''
word_count: 9
tokens: 12
keywords:
- dify
- platform
- llm
index_node_id: a1b2c3d4-e5f6-7890-abcd-000000000001
index_node_hash: abc123def456
hit_count: 0
enabled: true
disabled_at: null
disabled_by: null
status: completed
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
updated_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
indexing_at: 1741267200
completed_at: 1741267200
error: null
stopped_at: null
child_chunks: []
attachments: []
summary: null
doc_form: text_model
'400':
description: '`invalid_param` : The knowledge base uses high-quality indexing but its embedding
model is missing or misconfigured.'
content:
application/json:
examples:
invalid_param:
summary: invalid_param
value:
status: 400
code: invalid_param
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
'403':
description: '`forbidden` : Dataset api access is not enabled.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '- `not_found` : Dataset not found.
- `not_found` : Document not found.
- `not_found` : Segment not found.'
content:
application/json:
examples:
not_found_1:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found
value:
status: 404
code: not_found
message: Document not found.
not_found_3:
summary: not_found
value:
status: 404
code: not_found
message: Segment not found.
x-mint:
href: /en/api-reference/chunks/get-chunk
metadata:
title: Get Chunk
sidebarTitle: Get Chunk
post:
tags:
- Chunks
summary: Update Chunk
description: Update a chunk's fields. The update re-triggers indexing for that chunk.
operationId: updateSegment
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).
- name: segment_id
in: path
required: true
schema:
type: string
format: uuid
description: Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- segment
properties:
segment:
type: object
properties:
content:
type: string
description: Chunk text content.
answer:
type: string
description: Answer text for Q&A-mode (`qa_model`) documents.
keywords:
type: array
items:
type: string
description: Keywords for the chunk.
enabled:
type: boolean
description: Whether the chunk is enabled.
regenerate_child_chunks:
type: boolean
default: false
description: Whether to regenerate child chunks.
attachment_ids:
type: array
items:
type: string
description: Attachment file IDs.
summary:
type: string
nullable: true
description: Summary content for summary index.
description: Chunk data to update.
responses:
'200':
description: Chunk updated successfully.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Segment'
doc_form:
type: string
description: Document chunking mode used by this document.
examples:
success:
summary: Response Example
value:
data:
id: f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1
position: 1
document_id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
content: Dify is an open-source LLM app development platform.
sign_content: ''
answer: ''
word_count: 9
tokens: 12
keywords:
- dify
- platform
- llm
index_node_id: a1b2c3d4-e5f6-7890-abcd-000000000001
index_node_hash: abc123def456
hit_count: 0
enabled: true
disabled_at: null
disabled_by: null
status: completed
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
updated_at: 1741267200
updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
indexing_at: 1741267200
completed_at: 1741267200
error: null
stopped_at: null
child_chunks: []
attachments: []
summary: null
doc_form: text_model
'400':
description: '- `provider_not_initialize` : The knowledge base uses high-quality indexing but
its embedding model is missing or misconfigured.
- `invalid_param` : The chunk is indexing or disabled and cannot be updated, or index configuration
is invalid.'
content:
application/json:
examples:
provider_not_initialize:
summary: provider_not_initialize
value:
status: 400
code: provider_not_initialize
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
invalid_param_state:
summary: invalid_param (state)
value:
status: 400
code: invalid_param
message: Segment is indexing, please try again later
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : The capacity of the vector space has reached the limit of your subscription.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (vector space)
value:
status: 403
code: forbidden
message: The capacity of the vector space has reached the limit of your subscription.
forbidden_3:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '- `not_found` : Dataset not found.
- `not_found` : Document not found.
- `not_found` : Segment not found.'
content:
application/json:
examples:
not_found_1:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found
value:
status: 404
code: not_found
message: Document not found.
not_found_3:
summary: not_found
value:
status: 404
code: not_found
message: Segment not found.
'503':
description: '`service_unavailable` : Vector space usage could not be verified. Returned on
the Dify Cloud Sandbox plan only; retry the request later.'
content:
application/json:
examples:
service_unavailable:
summary: service_unavailable
value:
status: 503
code: service_unavailable
message: Unable to verify vector space usage right now. Please try again later.
x-mint:
href: /en/api-reference/chunks/update-chunk
metadata:
title: Update Chunk
sidebarTitle: Update Chunk
delete:
tags:
- Chunks
summary: Delete Chunk
description: Permanently delete a chunk from the document.
operationId: deleteSegment
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. Obtain it from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. Obtain it from [List Documents](/en/api-reference/documents/list-documents).
- name: segment_id
in: path
required: true
schema:
type: string
format: uuid
description: Chunk ID. Obtain it from [List Chunks](/en/api-reference/chunks/list-chunks).
responses:
'204':
description: Success.
'400':
description: '- `invalid_param` : The knowledge base uses high-quality indexing but its embedding
model is missing or misconfigured.
- `invalid_param` : The chunk is already being deleted by a concurrent request.'
content:
application/json:
examples:
invalid_param_model_setting:
summary: invalid_param (model setting)
value:
status: 400
code: invalid_param
message: No Embedding Model available. Please configure a valid provider in the Settings
-> Model Provider.
invalid_param_deleting:
summary: invalid_param (deleting)
value:
status: 400
code: invalid_param
message: Segment is deleting.
'403':
description: '- `forbidden` : Dataset api access is not enabled.
- `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '- `not_found` : Dataset not found.
- `not_found` : Document not found.
- `not_found` : Segment not found.'
content:
application/json:
examples:
not_found_1:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
not_found_2:
summary: not_found
value:
status: 404
code: not_found
message: Document not found.
not_found_3:
summary: not_found
value:
status: 404
code: not_found
message: Segment not found.
x-mint:
href: /en/api-reference/chunks/delete-chunk
metadata:
title: Delete Chunk
sidebarTitle: Delete Chunk
/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks:
post:
tags:
- Chunks
summary: Create Child Chunk
description: Create a child chunk under a parent chunk. Intended for documents that use the parent-child
(`hierarchical_model`) chunking mode.
operationId: createChildChunk
par
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dify/refs/heads/main/openapi/dify-chunks-api-openapi.yml