{
  "schemaVersion": "1.0",
  "title": "Dify segments and child chunks",
  "description": "Use this family to create, inspect, update, or delete document segments and their child chunks. The nine operations resolve every object through its workspace, dataset, document, and parent ownership chain.",
  "canonical": "https://getaip.org/docs/connectors/dify/capabilities/knowledge-segments-and-child-chunks",
  "route": "/docs/connectors/dify/capabilities/knowledge-segments-and-child-chunks",
  "source": "docs/connectors/dify/capabilities/knowledge-segments-and-child-chunks.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/capabilities/knowledge-segments-and-child-chunks.md",
    "txt": "/docs/download/connectors/dify/capabilities/knowledge-segments-and-child-chunks.txt",
    "json": "/docs/download/connectors/dify/capabilities/knowledge-segments-and-child-chunks.json",
    "pdf": "/docs/download/connectors/dify/capabilities/knowledge-segments-and-child-chunks.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify segments and child chunks\ndescription: >-\n  Maintain bounded document chunks through the frozen Dify knowledge\n  connector\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify segments and child chunks\n\nUse this family to create, inspect, update, or delete document segments and\ntheir child chunks. The nine operations resolve every object through its\nworkspace, dataset, document, and parent ownership chain.\n\nChunk content, answers, attachments, summaries, and errors can contain\nconfidential data. Approval must bind each mutation to the complete route\nidentity and intended index change.\n\n## Choose an operation\n\n| Operation suffix | Method and route | Purpose | Policy |\n|---|---|---|---|\n| `segment.create` | `POST /v1/datasets/{dataset_id}/documents/{document_id}/segments` | Create one or more segments | Medium mutation; approval and key required |\n| `segment.list` | `GET /v1/datasets/{dataset_id}/documents/{document_id}/segments` | List and filter segments | Low-risk read; retry supported |\n| `segment.get` | `GET /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}` | Read one segment | Low-risk read; retry supported |\n| `segment.update` | `POST /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}` | Update content, index, or availability | Medium mutation; approval and key required |\n| `segment.delete` | `DELETE /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}` | Delete one segment | High mutation; approval and key required |\n| `child_chunk.create` | `POST /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks` | Create one child chunk | Medium mutation; approval and key required |\n| `child_chunk.list` | `GET /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks` | List child chunks | Low-risk read; retry supported |\n| `child_chunk.update` | `PATCH /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}` | Replace child content | Medium mutation; approval and key required |\n| `child_chunk.delete` | `DELETE /v1/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}` | Delete one child chunk | High mutation; approval and key required |\n\nThese Tool operations have knowledge scope and no app-mode projection. The\ncapability template is:\n\n```text\ncap:dify:knowledge:<credential_id>:<operation>\n```\n\nThe provider requires UUID route IDs. It resolves a segment through the\ndataset and document, then resolves a child through that segment. Preserve the\ncomplete chain in approval and audit evidence.\n\n## Create document segments\n\nThe document must exist, be enabled, and have completed indexing. A\nhigh-quality dataset also requires its configured embedding model.\n\n`segment.create` requires a non-empty `body.segments` array. Each item requires\nnon-blank `content` and can include `answer`, `keywords`, and `attachment_ids`.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"body\": {\n    \"segments\": [\n      {\n        \"content\": \"Refund requests must arrive within thirty days.\",\n        \"keywords\": [\"refund\", \"window\"],\n        \"attachment_ids\": [\"attachment-0190\"]\n      }\n    ]\n  }\n}\n```\n\nA `qa_model` document also requires a non-blank `answer` for every item. The\nprovider attachment limit is configurable and defaults to ten per segment.\n\nThe provider setting `DATASET_MAX_SEGMENTS_PER_REQUEST` controls the item\ncount. Its pinned default is zero, meaning no provider-specific count ceiling.\nApply a tenant policy bound before dispatch.\n\nSuccess returns `data` with created segments and the document `doc_form`.\nSegment fields include IDs, content, answer, keywords, token and word counts,\nindex state, child chunks, attachments, and optional summary.\n\n## List or inspect segments\n\n`segment.list` accepts `page`, `limit`, repeated `status`, and `keyword` through\nAction `query`. Page and limit must be at least 1; provider pagination caps the\nlimit at 100.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"query\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"status\": [\"completed\", \"error\"],\n    \"keyword\": \"refund\"\n  }\n}\n```\n\nThe list result contains `data`, `doc_form`, `total`, `has_more`, `limit`, and\n`page`. Results are ordered by segment position and ID.\n\nUse `segment.get` with the full route chain for one record. Its result contains\n`data` and `doc_form`, including the summary when one exists.\n\n## Update one segment\n\n`segment.update` wraps optional changes inside `body.segment`:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segment_id\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"body\": {\n    \"segment\": {\n      \"content\": \"Refund requests must arrive within thirty calendar days.\",\n      \"keywords\": [\"refund\", \"calendar-days\"],\n      \"enabled\": true,\n      \"regenerate_child_chunks\": false,\n      \"attachment_ids\": [],\n      \"summary\": \"Thirty-day refund request window.\"\n    }\n  }\n}\n```\n\nThe object can contain `content`, `answer`, `keywords`, `enabled`,\n`regenerate_child_chunks`, `attachment_ids`, and `summary`. QA content changes\nshould preserve the intended answer.\n\nSetting `enabled` to false disables the segment and schedules index removal.\nA disabled segment cannot accept ordinary edits; enable it through an approved\nupdate first.\n\n`regenerate_child_chunks` applies to a parent-child document and requires\nhigh-quality indexing. Content, keywords, attachments, and summary changes can\nalso update vector or summary index state.\n\nThe pinned provider can catch an indexing failure and return a segment marked\n`error`. Inspect `data.status` and `data.error`; HTTP success alone does not\nprove a usable index.\n\n## Delete one segment\n\n`segment.delete` requires the complete dataset, document, and segment chain.\nIt removes the segment and its associated index state and returns empty status\n204.\n\nThe provider prevents overlapping delete work with a short-lived cache key.\nThe connector represents an empty successful body as `null` and provides no\nrollback contract.\n\n## Maintain child chunks\n\nUse child operations for the explicit children below one known parent segment.\nRoute ownership does not by itself prove that the document uses a\nparent-child processing form.\n\nCreate requires `body.content`:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segment_id\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"body\": {\n    \"content\": \"Submit the request through the approved support channel.\"\n  }\n}\n```\n\nThe provider creates vector state and returns one child record. An indexing\nfailure rolls back that provider transaction and returns an error.\n\n`child_chunk.list` accepts page, limit, and keyword. Page and limit must be at\nleast 1, and limit is capped at 100. The result contains `data`, `total`,\n`total_pages`, `page`, and `limit`.\n\nUpdate requires the full route chain and `body.content`. It replaces content,\nword count, update identity, and vector state. Delete removes the record and\nits vector entry, then returns empty status 204.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segment_id\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"child_chunk_id\": \"0190c42f-2d5a-7000-8000-000000000604\",\n  \"body\": {\n    \"content\": \"Submit the request through the verified support portal.\"\n  }\n}\n```\n\n## Apply mutation governance\n\nAll six mutations require a non-blank Action idempotency key of at most 512\nbytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates\nthe input hash on collision.\n\nThe key does not prove provider deduplication. These operations publish no\nautomatic retry, transaction, reconciliation, cancellation, or compensation\nsupport.\n\nTreat content, answers, keywords, attachments, summaries, vector identity,\nstatuses, and errors as confidential PII-bearing data. Redact them from general\nlogs.\n\n## Recover safely\n\n| Observation | Decision |\n|---|---|\n| Any route ID or body is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Document is incomplete or disabled | Finish indexing or authorize the intended enable transition first |\n| High-quality model is unavailable | Repair the pinned workspace model before another mutation |\n| Segment create response is lost | List segments and compare content before another create |\n| Segment update returns status error | Preserve the error and inspect content and index state before repair |\n| Child vector mutation fails | Read the same child route before authorizing another mutation |\n| Delete response is lost | Read the exact ownership chain before considering reconstruction |\n| List pagination reaches the cap | Continue by page without widening connector bounds |\n| Returned content crosses an ownership boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, complete\nroute chain, returned status, and provider evidence needed to settle an\nambiguous outcome.\n\n## Related documentation\n\n- [Dify capability index](README.md)\n- [Dify knowledge documents and indexing](knowledge-documents-and-indexing.md)\n- [Dify connector configuration](../reference/configuration.md)\n- [Authentication and credential scopes](../getting-started/authentication-and-credential-scopes.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify segments and child chunks\n\nUse this family to create, inspect, update, or delete document segments and\ntheir child chunks. The nine operations resolve every object through its\nworkspace, dataset, document, and parent ownership chain.\n\nChunk content, answers, attachments, summaries, and errors can contain\nconfidential data. Approval must bind each mutation to the complete route\nidentity and intended index change.\n\nChoose an operation\n\n| Operation suffix | Method and route | Purpose | Policy |\n\n| segment.create | POST /v1/datasets/{datasetid}/documents/{documentid}/segments | Create one or more segments | Medium mutation; approval and key required |\n| segment.list | GET /v1/datasets/{datasetid}/documents/{documentid}/segments | List and filter segments | Low-risk read; retry supported |\n| segment.get | GET /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid} | Read one segment | Low-risk read; retry supported |\n| segment.update | POST /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid} | Update content, index, or availability | Medium mutation; approval and key required |\n| segment.delete | DELETE /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid} | Delete one segment | High mutation; approval and key required |\n| childchunk.create | POST /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid}/childchunks | Create one child chunk | Medium mutation; approval and key required |\n| childchunk.list | GET /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid}/childchunks | List child chunks | Low-risk read; retry supported |\n| childchunk.update | PATCH /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid}/childchunks/{childchunkid} | Replace child content | Medium mutation; approval and key required |\n| childchunk.delete | DELETE /v1/datasets/{datasetid}/documents/{documentid}/segments/{segmentid}/childchunks/{childchunkid} | Delete one child chunk | High mutation; approval and key required |\n\nThese Tool operations have knowledge scope and no app-mode projection. The\ncapability template is:\n\ncap:dify:knowledge::\n\nThe provider requires UUID route IDs. It resolves a segment through the\ndataset and document, then resolves a child through that segment. Preserve the\ncomplete chain in approval and audit evidence.\n\nCreate document segments\n\nThe document must exist, be enabled, and have completed indexing. A\nhigh-quality dataset also requires its configured embedding model.\n\nsegment.create requires a non-empty body.segments array. Each item requires\nnon-blank content and can include answer, keywords, and attachmentids.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"body\": {\n    \"segments\": [\n      {\n        \"content\": \"Refund requests must arrive within thirty days.\",\n        \"keywords\": [\"refund\", \"window\"],\n        \"attachmentids\": [\"attachment-0190\"]\n      }\n    ]\n  }\n}\n\nA qamodel document also requires a non-blank answer for every item. The\nprovider attachment limit is configurable and defaults to ten per segment.\n\nThe provider setting DATASETMAXSEGMENTSPERREQUEST controls the item\ncount. Its pinned default is zero, meaning no provider-specific count ceiling.\nApply a tenant policy bound before dispatch.\n\nSuccess returns data with created segments and the document docform.\nSegment fields include IDs, content, answer, keywords, token and word counts,\nindex state, child chunks, attachments, and optional summary.\n\nList or inspect segments\n\nsegment.list accepts page, limit, repeated status, and keyword through\nAction query. Page and limit must be at least 1; provider pagination caps the\nlimit at 100.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"query\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"status\": [\"completed\", \"error\"],\n    \"keyword\": \"refund\"\n  }\n}\n\nThe list result contains data, docform, total, hasmore, limit, and\npage. Results are ordered by segment position and ID.\n\nUse segment.get with the full route chain for one record. Its result contains\ndata and docform, including the summary when one exists.\n\nUpdate one segment\n\nsegment.update wraps optional changes inside body.segment:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segmentid\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"body\": {\n    \"segment\": {\n      \"content\": \"Refund requests must arrive within thirty calendar days.\",\n      \"keywords\": [\"refund\", \"calendar-days\"],\n      \"enabled\": true,\n      \"regeneratechildchunks\": false,\n      \"attachmentids\": [],\n      \"summary\": \"Thirty-day refund request window.\"\n    }\n  }\n}\n\nThe object can contain content, answer, keywords, enabled,\nregeneratechildchunks, attachmentids, and summary. QA content changes\nshould preserve the intended answer.\n\nSetting enabled to false disables the segment and schedules index removal.\nA disabled segment cannot accept ordinary edits; enable it through an approved\nupdate first.\n\nregeneratechildchunks applies to a parent-child document and requires\nhigh-quality indexing. Content, keywords, attachments, and summary changes can\nalso update vector or summary index state.\n\nThe pinned provider can catch an indexing failure and return a segment marked\nerror. Inspect data.status and data.error; HTTP success alone does not\nprove a usable index.\n\nDelete one segment\n\nsegment.delete requires the complete dataset, document, and segment chain.\nIt removes the segment and its associated index state and returns empty status\n204. The provider prevents overlapping delete work with a short-lived cache key.\nThe connector represents an empty successful body as null and provides no\nrollback contract.\n\nMaintain child chunks\n\nUse child operations for the explicit children below one known parent segment.\nRoute ownership does not by itself prove that the document uses a\nparent-child processing form.\n\nCreate requires body.content:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segmentid\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"body\": {\n    \"content\": \"Submit the request through the approved support channel.\"\n  }\n}\n\nThe provider creates vector state and returns one child record. An indexing\nfailure rolls back that provider transaction and returns an error.\n\nchildchunk.list accepts page, limit, and keyword. Page and limit must be at\nleast 1, and limit is capped at 100. The result contains data, total,\ntotalpages, page, and limit.\n\nUpdate requires the full route chain and body.content. It replaces content,\nword count, update identity, and vector state. Delete removes the record and\nits vector entry, then returns empty status 204.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000601\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000602\",\n  \"segmentid\": \"0190c42f-2d5a-7000-8000-000000000603\",\n  \"childchunkid\": \"0190c42f-2d5a-7000-8000-000000000604\",\n  \"body\": {\n    \"content\": \"Submit the request through the verified support portal.\"\n  }\n}\n\nApply mutation governance\n\nAll six mutations require a non-blank Action idempotency key of at most 512\nbytes. AIP retains its tenant-scoped reservation for 24 hours and revalidates\nthe input hash on collision.\n\nThe key does not prove provider deduplication. These operations publish no\nautomatic retry, transaction, reconciliation, cancellation, or compensation\nsupport.\n\nTreat content, answers, keywords, attachments, summaries, vector identity,\nstatuses, and errors as confidential PII-bearing data. Redact them from general\nlogs.\n\nRecover safely\n\n| Observation | Decision |\n\n| Any route ID or body is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Document is incomplete or disabled | Finish indexing or authorize the intended enable transition first |\n| High-quality model is unavailable | Repair the pinned workspace model before another mutation |\n| Segment create response is lost | List segments and compare content before another create |\n| Segment update returns status error | Preserve the error and inspect content and index state before repair |\n| Child vector mutation fails | Read the same child route before authorizing another mutation |\n| Delete response is lost | Read the exact ownership chain before considering reconstruction |\n| List pagination reaches the cap | Continue by page without widening connector bounds |\n| Returned content crosses an ownership boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, complete\nroute chain, returned status, and provider evidence needed to settle an\nambiguous outcome.\n\nRelated documentation\n• Dify capability index (README.md)\n• Dify knowledge documents and indexing (knowledge-documents-and-indexing.md)\n• Dify connector configuration (../reference/configuration.md)\n• Authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "f0fa8fd2aefcea10eddf990c11290657c3ee0f7edcccd7ca5d955b0bede74b85"
  }
}