Dify Octri Demo
PATCH/datasets/{dataset_id}/documents/{document_id}

Update Document

Updates a document by uploading a new file, then re-indexes it. This is the canonical endpoint for file-based document updates. Track progress with the returned batch ID via Get Document Indexing Status.

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

2 parameters · 2 body fields
dataset_idstringrequired
Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).
document_idstringrequired
Document ID. From [List Documents](/en/api-reference/documents/list-documents).
datastringoptional
JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.
filestringoptional
File to upload, capped at 15 MB by default. Self-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB.

7 status codes
200Document updated successfully.
batchstringoptional
Batch ID for tracking indexing progress.
documentobjectoptional
400- `too_many_files` : Only one file is allowed per request. - `filename_not_exists_error` : The uploaded file has no filename. - `provider_not_initialize` : No model provider credentials are configured for the workspace. - `invalid_param` : The document is not available for update (only available documents can be updated).

4 documented failures

  • filename_not_exists_error

    The specified filename does not exist.

    filename_not_exists_error

  • invalid_param

    Document is not available

    invalid_param (not available)

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • too_many_files

    Only one file is allowed.

    too_many_files

403- `forbidden` : Knowledge base 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` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404- `not_found` : Knowledge base not found. - `not_found` : Document not found.

One documented failure

  • not_found

    Dataset not found.

    not_found

413`file_too_large` : The uploaded file exceeds the maximum size.

One documented failure

  • file_too_large

    File size exceeded.

    file_too_large

415`unsupported_file_type` : The uploaded file's type is not supported.

One documented failure

  • unsupported_file_type

    File type not allowed.

    unsupported_file_type

503`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.

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: - too_many_files : Only one file is allowed per request.

  • filename_not_exists_error : The uploaded file has no filename.
  • provider_not_initialize : No model provider credentials are configured for the workspace.
  • invalid_param : The document is not available for update (only available documents can be updated). A 403 is returned: - forbidden : Knowledge base 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 : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them. A 404 is returned: - not_found : Knowledge base not found.
  • not_found : Document not found. A 413 is returned: file_too_large : The uploaded file exceeds the maximum size. A 415 is returned: unsupported_file_type : The uploaded file's type is not supported. A 503 is returned: service_unavailable : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.