{
  "schemaVersion": "1.0",
  "title": "Dify knowledge documents and indexing",
  "description": "Use this family to create or replace knowledge documents, inspect their state, track indexing, control availability, download approved sources, or delete one document. All twelve operations use a workspace-scoped knowledge credential.",
  "canonical": "https://getaip.org/docs/connectors/dify/capabilities/knowledge-documents-and-indexing",
  "route": "/docs/connectors/dify/capabilities/knowledge-documents-and-indexing",
  "source": "docs/connectors/dify/capabilities/knowledge-documents-and-indexing.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/capabilities/knowledge-documents-and-indexing.md",
    "txt": "/docs/download/connectors/dify/capabilities/knowledge-documents-and-indexing.txt",
    "json": "/docs/download/connectors/dify/capabilities/knowledge-documents-and-indexing.json",
    "pdf": "/docs/download/connectors/dify/capabilities/knowledge-documents-and-indexing.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify knowledge documents and indexing\ndescription: >-\n  Create, inspect, control, download, and remove indexed documents through the\n  frozen Dify connector\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify knowledge documents and indexing\n\nUse this family to create or replace knowledge documents, inspect their state,\ntrack indexing, control availability, download approved sources, or delete one\ndocument. All twelve operations use a workspace-scoped knowledge credential.\n\nDocument content, metadata, source links, and indexing errors can contain\nconfidential data. Approval must identify the workspace, dataset, document,\nsource content, processing change, and result handling.\n\n## Choose an operation\n\n| Operation suffix | Method and route | Result | Policy |\n|---|---|---|---|\n| `document.status.update` | `PATCH /v1/datasets/{dataset_id}/documents/status/{action}` | JSON success | Medium mutation; approval and key required |\n| `document.text.create` | `POST /v1/datasets/{dataset_id}/document/create-by-text` | Document and batch | Medium mutation; approval and key required |\n| `document.text.update` | `POST /v1/datasets/{dataset_id}/documents/{document_id}/update-by-text` | Document and batch | Medium mutation; approval and key required |\n| `document.file.create` | `POST /v1/datasets/{dataset_id}/document/create-by-file` | Document and batch | Medium mutation; approval and key required |\n| `document.file.update` | `POST /v1/datasets/{dataset_id}/documents/{document_id}/update-by-file` | Document and batch | Medium compatibility mutation; approval and key required |\n| `document.list` | `GET /v1/datasets/{dataset_id}/documents` | Paginated JSON | Low-risk read; retry supported |\n| `document.download_zip` | `POST /v1/datasets/{dataset_id}/documents/download-zip` | Bounded ZIP | Medium mutation; approval and key required |\n| `document.indexing_status` | `GET /v1/datasets/{dataset_id}/documents/{batch}/indexing-status` | Status list | Low-risk read; retry supported |\n| `document.download` | `GET /v1/datasets/{dataset_id}/documents/{document_id}/download` | Signed URL descriptor | Low-risk read; retry supported |\n| `document.get` | `GET /v1/datasets/{dataset_id}/documents/{document_id}` | Document detail | Low-risk read; retry supported |\n| `document.update` | `PATCH /v1/datasets/{dataset_id}/documents/{document_id}` | Document and batch | Medium canonical mutation; approval and key required |\n| `document.delete` | `DELETE /v1/datasets/{dataset_id}/documents/{document_id}` | Empty 204 | 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\nDataset and document route identifiers must belong to the selected workspace.\nThe pinned provider requires UUIDs for those route values.\n\n## List or inspect documents\n\n`document.list` accepts `page`, `limit`, `keyword`, and `status` through Action\n`query`. Pagination defaults to page 1 and limit 20; the provider caps the\nlimit at 100.\n\nStatus accepts `queuing`, `indexing`, `paused`, `error`, `available`,\n`disabled`, or `archived`. Keyword filters by document name.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"query\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"status\": \"available\",\n    \"keyword\": \"refund\"\n  }\n}\n```\n\nThe response contains `data`, `has_more`, `limit`, `total`, and `page`.\nRecords can expose source identity, name, token and word counts, indexing\nstate, display state, metadata, hit count, document form, and summary state.\n\n`document.get` accepts a `metadata` query value of `all`, `only`, or `without`.\nThe default `all` includes document metadata. `only` returns `id`, `doc_type`,\nand `doc_metadata`; `without` omits the last two metadata fields.\n\n## Create a text document\n\n`document.text.create` requires `body.name` and `body.text`. It accepts\nprocessing rules, retrieval settings, model identifiers, and these document\nforms:\n\n- `text_model` for ordinary chunks\n- `hierarchical_model` for parent and child chunks\n- `qa_model` for extracted question-and-answer pairs\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"body\": {\n    \"name\": \"Refund policy\",\n    \"text\": \"Approved customers may request a refund within the stated window.\",\n    \"doc_form\": \"text_model\",\n    \"doc_language\": \"English\",\n    \"indexing_technique\": \"high_quality\"\n  }\n}\n```\n\nThe first document requires `indexing_technique` when the dataset has none.\nLater documents inherit the dataset setting. The default form is `text_model`,\nand the default processing language is English.\n\nThe provider stores the text as an uploaded source and returns `document` plus\n`batch`. Indexing continues asynchronously after that response.\n\n## Update a text document\n\n`document.text.update` accepts name, text, processing rules, form, language,\nand retrieval settings. When `text` is supplied, `name` is also required.\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"document_id\": \"0190c42f-2d5a-7000-8000-000000000502\",\n  \"body\": {\n    \"name\": \"Refund policy, reviewed\",\n    \"text\": \"Approved customers may request a refund within thirty days.\"\n  }\n}\n```\n\nContent replacement creates a new source representation and re-triggers\nindexing. Preserve the returned batch rather than treating the HTTP response\nas completed indexing.\n\n## Create or update from a file\n\nAll three multipart operations require Action `file` at the connector boundary:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"file\": {\n    \"filename\": \"refund-policy.pdf\",\n    \"content_type\": \"application/pdf\",\n    \"content_base64\": \"JVBERi0=\"\n  },\n  \"body\": {\n    \"doc_form\": \"text_model\",\n    \"doc_language\": \"English\",\n    \"indexing_technique\": \"high_quality\"\n  }\n}\n```\n\nThe connector sends the file plus serialized JSON in multipart `data`. It\nrequires a safe basename and caps decoded content at 32 MiB. Provider file\ntype, tenant quota, and configured upload limits can be stricter.\n\nUse `document.file.create` for a new internal dataset document. File upload is\nnot supported for an external dataset. The provider permits exactly one file\nand returns document plus batch.\n\nPrefer canonical `document.update` for an existing document. The\n`document.file.update` operation uses the pinned provider's compatibility POST\nroute. Both reach the same update helper and re-trigger indexing.\n\nThe provider PATCH route can update settings without replacement bytes, but\nthe connector's multipart schema still requires `file`. This connector version\ndoes not expose settings-only PATCH input.\n\n## Track indexing by batch\n\nEvery content create or replacement returns a `batch`. Call\n`document.indexing_status` with the same dataset and batch:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"batch\": \"batch-0190c42f\"\n}\n```\n\nNormal progress moves through `waiting`, `parsing`, `cleaning`, `splitting`,\n`indexing`, and `completed`. A document can instead report `paused`, an error,\nor stopped evidence.\n\nEach status record contains document ID, current phase, processing timestamps,\nerror, and completed and total segment counts. A completed HTTP poll is not a\nterminal indexing state unless every intended document reports terminal\nevidence.\n\nThe connector has no provider indexing cancellation operation. Use status\ncontrol only when its documented action matches the intended lifecycle change.\n\n## Change document availability\n\n`document.status.update` accepts `action` values `enable`, `disable`, `archive`,\nor `un_archive`. The body carries the bounded document set:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"action\": \"disable\",\n  \"body\": {\n    \"document_ids\": [\n      \"0190c42f-2d5a-7000-8000-000000000502\"\n    ]\n  }\n}\n```\n\nDify checks dataset permission and model configuration before applying the\nbatch action. It rejects invalid transitions, including changes that conflict\nwith active indexing.\n\nSuccess returns `result: success`. Confirm the resulting display state with a\ndocument read before releasing correlation evidence.\n\n## Download approved sources\n\n`document.download` returns a JSON object containing a signed `url` for the\noriginal uploaded file. It does not return the file bytes. Apply outbound URL,\nexpiry, authorization, and content controls before following that URL.\n\n`document.download_zip` accepts 1 to 100 UUID document IDs:\n\n```json\n{\n  \"dataset_id\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"body\": {\n    \"document_ids\": [\n      \"0190c42f-2d5a-7000-8000-000000000502\"\n    ]\n  }\n}\n```\n\nOnly approved uploaded-file documents enter the provider archive. The\nconnector buffers and returns base64 ZIP data in its binary result envelope.\nIts configured response limit defaults to 8 MiB and permits 1 to 64 MiB.\n\nThe connector classifies ZIP generation as a mutation because it uses POST.\nIt requires approval and a key and publishes no safe retry.\n\n## Delete one document\n\n`document.delete` permanently removes the document and all chunks. Dify rejects\nthe request while the document is indexing or when it is archived.\n\nSuccess returns empty status 204, represented as `null` in the generic\nconnector result. There is no rollback or reconstruction contract.\n\n## Apply mutation governance\n\nAll eight 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, indexing cancellation, or\ncompensation support.\n\nTreat text, files, metadata, signed URLs, ZIP bytes, processing rules, model\nchoices, statuses, and errors as confidential PII-bearing data. Redact them\nfrom general logs.\n\n## Recover safely\n\n| Observation | Decision |\n|---|---|\n| UUID, action, query, body, or file is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Create or replacement returns a batch | Persist it and poll indexing status until terminal evidence |\n| Mutation response is lost after dispatch | Read the document and indexing state before another mutation |\n| Indexing pauses or errors | Preserve the batch and error, repair the cause, then authorize the next action |\n| Status change returns success | Confirm the document display state through a read |\n| Signed URL is missing or expired | Request a new descriptor after rechecking authorization |\n| ZIP exceeds the response bound | Reduce the approved document set; do not raise limits blindly |\n| Delete is blocked by indexing or archive state | Resolve that state through an approved lifecycle action first |\n| Returned content crosses a workspace or dataset boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, dataset,\ndocument, batch, status, and bounded provider evidence needed to settle an\nambiguous outcome.\n\n## Related documentation\n\n- [Dify capability index](README.md)\n- [Dify knowledge bases, tags, and retrieval](knowledge-datasets-tags-and-retrieval.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 knowledge documents and indexing\n\nUse this family to create or replace knowledge documents, inspect their state,\ntrack indexing, control availability, download approved sources, or delete one\ndocument. All twelve operations use a workspace-scoped knowledge credential.\n\nDocument content, metadata, source links, and indexing errors can contain\nconfidential data. Approval must identify the workspace, dataset, document,\nsource content, processing change, and result handling.\n\nChoose an operation\n\n| Operation suffix | Method and route | Result | Policy |\n\n| document.status.update | PATCH /v1/datasets/{datasetid}/documents/status/{action} | JSON success | Medium mutation; approval and key required |\n| document.text.create | POST /v1/datasets/{datasetid}/document/create-by-text | Document and batch | Medium mutation; approval and key required |\n| document.text.update | POST /v1/datasets/{datasetid}/documents/{documentid}/update-by-text | Document and batch | Medium mutation; approval and key required |\n| document.file.create | POST /v1/datasets/{datasetid}/document/create-by-file | Document and batch | Medium mutation; approval and key required |\n| document.file.update | POST /v1/datasets/{datasetid}/documents/{documentid}/update-by-file | Document and batch | Medium compatibility mutation; approval and key required |\n| document.list | GET /v1/datasets/{datasetid}/documents | Paginated JSON | Low-risk read; retry supported |\n| document.downloadzip | POST /v1/datasets/{datasetid}/documents/download-zip | Bounded ZIP | Medium mutation; approval and key required |\n| document.indexingstatus | GET /v1/datasets/{datasetid}/documents/{batch}/indexing-status | Status list | Low-risk read; retry supported |\n| document.download | GET /v1/datasets/{datasetid}/documents/{documentid}/download | Signed URL descriptor | Low-risk read; retry supported |\n| document.get | GET /v1/datasets/{datasetid}/documents/{documentid} | Document detail | Low-risk read; retry supported |\n| document.update | PATCH /v1/datasets/{datasetid}/documents/{documentid} | Document and batch | Medium canonical mutation; approval and key required |\n| document.delete | DELETE /v1/datasets/{datasetid}/documents/{documentid} | Empty 204 | 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\nDataset and document route identifiers must belong to the selected workspace.\nThe pinned provider requires UUIDs for those route values.\n\nList or inspect documents\n\ndocument.list accepts page, limit, keyword, and status through Action\nquery. Pagination defaults to page 1 and limit 20; the provider caps the\nlimit at 100.\n\nStatus accepts queuing, indexing, paused, error, available,\ndisabled, or archived. Keyword filters by document name.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"query\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"status\": \"available\",\n    \"keyword\": \"refund\"\n  }\n}\n\nThe response contains data, hasmore, limit, total, and page.\nRecords can expose source identity, name, token and word counts, indexing\nstate, display state, metadata, hit count, document form, and summary state.\n\ndocument.get accepts a metadata query value of all, only, or without.\nThe default all includes document metadata. only returns id, doctype,\nand docmetadata; without omits the last two metadata fields.\n\nCreate a text document\n\ndocument.text.create requires body.name and body.text. It accepts\nprocessing rules, retrieval settings, model identifiers, and these document\nforms:\n• textmodel for ordinary chunks\n• hierarchicalmodel for parent and child chunks\n• qamodel for extracted question-and-answer pairs\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"body\": {\n    \"name\": \"Refund policy\",\n    \"text\": \"Approved customers may request a refund within the stated window.\",\n    \"docform\": \"textmodel\",\n    \"doclanguage\": \"English\",\n    \"indexingtechnique\": \"highquality\"\n  }\n}\n\nThe first document requires indexingtechnique when the dataset has none.\nLater documents inherit the dataset setting. The default form is textmodel,\nand the default processing language is English.\n\nThe provider stores the text as an uploaded source and returns document plus\nbatch. Indexing continues asynchronously after that response.\n\nUpdate a text document\n\ndocument.text.update accepts name, text, processing rules, form, language,\nand retrieval settings. When text is supplied, name is also required.\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"documentid\": \"0190c42f-2d5a-7000-8000-000000000502\",\n  \"body\": {\n    \"name\": \"Refund policy, reviewed\",\n    \"text\": \"Approved customers may request a refund within thirty days.\"\n  }\n}\n\nContent replacement creates a new source representation and re-triggers\nindexing. Preserve the returned batch rather than treating the HTTP response\nas completed indexing.\n\nCreate or update from a file\n\nAll three multipart operations require Action file at the connector boundary:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"file\": {\n    \"filename\": \"refund-policy.pdf\",\n    \"contenttype\": \"application/pdf\",\n    \"contentbase64\": \"JVBERi0=\"\n  },\n  \"body\": {\n    \"docform\": \"textmodel\",\n    \"doclanguage\": \"English\",\n    \"indexingtechnique\": \"highquality\"\n  }\n}\n\nThe connector sends the file plus serialized JSON in multipart data. It\nrequires a safe basename and caps decoded content at 32 MiB. Provider file\ntype, tenant quota, and configured upload limits can be stricter.\n\nUse document.file.create for a new internal dataset document. File upload is\nnot supported for an external dataset. The provider permits exactly one file\nand returns document plus batch.\n\nPrefer canonical document.update for an existing document. The\ndocument.file.update operation uses the pinned provider's compatibility POST\nroute. Both reach the same update helper and re-trigger indexing.\n\nThe provider PATCH route can update settings without replacement bytes, but\nthe connector's multipart schema still requires file. This connector version\ndoes not expose settings-only PATCH input.\n\nTrack indexing by batch\n\nEvery content create or replacement returns a batch. Call\ndocument.indexingstatus with the same dataset and batch:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"batch\": \"batch-0190c42f\"\n}\n\nNormal progress moves through waiting, parsing, cleaning, splitting,\nindexing, and completed. A document can instead report paused, an error,\nor stopped evidence.\n\nEach status record contains document ID, current phase, processing timestamps,\nerror, and completed and total segment counts. A completed HTTP poll is not a\nterminal indexing state unless every intended document reports terminal\nevidence.\n\nThe connector has no provider indexing cancellation operation. Use status\ncontrol only when its documented action matches the intended lifecycle change.\n\nChange document availability\n\ndocument.status.update accepts action values enable, disable, archive,\nor unarchive. The body carries the bounded document set:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"action\": \"disable\",\n  \"body\": {\n    \"documentids\": [\n      \"0190c42f-2d5a-7000-8000-000000000502\"\n    ]\n  }\n}\n\nDify checks dataset permission and model configuration before applying the\nbatch action. It rejects invalid transitions, including changes that conflict\nwith active indexing.\n\nSuccess returns result: success. Confirm the resulting display state with a\ndocument read before releasing correlation evidence.\n\nDownload approved sources\n\ndocument.download returns a JSON object containing a signed url for the\noriginal uploaded file. It does not return the file bytes. Apply outbound URL,\nexpiry, authorization, and content controls before following that URL.\n\ndocument.downloadzip accepts 1 to 100 UUID document IDs:\n\n{\n  \"datasetid\": \"0190c42f-2d5a-7000-8000-000000000501\",\n  \"body\": {\n    \"documentids\": [\n      \"0190c42f-2d5a-7000-8000-000000000502\"\n    ]\n  }\n}\n\nOnly approved uploaded-file documents enter the provider archive. The\nconnector buffers and returns base64 ZIP data in its binary result envelope.\nIts configured response limit defaults to 8 MiB and permits 1 to 64 MiB.\n\nThe connector classifies ZIP generation as a mutation because it uses POST.\nIt requires approval and a key and publishes no safe retry.\n\nDelete one document\n\ndocument.delete permanently removes the document and all chunks. Dify rejects\nthe request while the document is indexing or when it is archived.\n\nSuccess returns empty status 204, represented as null in the generic\nconnector result. There is no rollback or reconstruction contract.\n\nApply mutation governance\n\nAll eight 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, indexing cancellation, or\ncompensation support.\n\nTreat text, files, metadata, signed URLs, ZIP bytes, processing rules, model\nchoices, statuses, and errors as confidential PII-bearing data. Redact them\nfrom general logs.\n\nRecover safely\n\n| Observation | Decision |\n\n| UUID, action, query, body, or file is rejected before dispatch | Correct the bounded request without claiming a provider effect |\n| Create or replacement returns a batch | Persist it and poll indexing status until terminal evidence |\n| Mutation response is lost after dispatch | Read the document and indexing state before another mutation |\n| Indexing pauses or errors | Preserve the batch and error, repair the cause, then authorize the next action |\n| Status change returns success | Confirm the document display state through a read |\n| Signed URL is missing or expired | Request a new descriptor after rechecking authorization |\n| ZIP exceeds the response bound | Reduce the approved document set; do not raise limits blindly |\n| Delete is blocked by indexing or archive state | Resolve that state through an approved lifecycle action first |\n| Returned content crosses a workspace or dataset boundary | Stop traffic and treat the event as an isolation incident |\n\nPreserve the Action ID, digest, approval, idempotency key, credential, dataset,\ndocument, batch, status, and bounded provider evidence needed to settle an\nambiguous outcome.\n\nRelated documentation\n• Dify capability index (README.md)\n• Dify knowledge bases, tags, and retrieval (knowledge-datasets-tags-and-retrieval.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": "93e29bd0523735452f98906152cd91ee0f415da7d5d861ec8857e7eb272518b2"
  }
}