Dify Octri Demo
POST/datasets/{dataset_id}/documents/{document_id}/update-by-text

Update document content or processing configuration

Updates a document's text, name, or processing and retrieval configuration. Supply text to replace the document content and name when you provide text; select processing and retrieval options as needed. Text changes trigger re-indexing, and the response includes a batch ID for tracking indexing progress.

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

2 parameters · 6 body fields
dataset_idstringrequired
The knowledge base identifier in UUID format.
document_idstringrequired
The document identifier in UUID format.

Document content and optional processing and retrieval configuration. Provide name when supplying text; process_rule requires mode, and retrieval_model requires search_method, reranking_enable, top_k, and `score_threshold_enabled.

doc_formstringoptional
`text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction.
Allowed:text_modelhierarchical_modelqa_modelDefault:text_model
doc_languagestringoptional
Language of the document for processing optimization.
Default:English
namestringoptional
Document name. Required when `text` is provided.
process_ruleobjectoptional
Processing rules for chunking.
retrieval_modelobjectoptional
Retrieval configuration. Includes `metadata_filtering_conditions` with `conditions` and `logical_operator`; `reranking_enable`, `reranking_mode`, and `reranking_model` with `reranking_model_name` and `reranking_provider_name`; `score_threshold` and `score_threshold_enabled`; `search_method`; `top_k`; and `weights` with `keyword_setting`, `vector_setting`, and `weight_type`. `reranking_mode` is `reranking_model` or `weighted_score` and is required when `reranking_enable` is true. `search_method` is `keyword_search`, `semantic_search`, `full_text_search`, or `hybrid_search`.
textstringoptional
Document text content.

5 status codes
200Returns the updated document object and a `batch` identifier for tracking indexing progress.
batchstringoptional
Batch ID for tracking indexing progress.
documentobjectoptional
400Returned when the document is unavailable for update, `doc_form` is invalid, or `name` is missing when `text` is supplied.

2 documented failures

  • invalid_param

    name is required when text is provided.

    invalid_param (name required)

  • provider_not_initialize

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

    provider_not_initialize

403Returned when knowledge base API access is disabled, a subscription limit prevents the operation, or the API key is not scoped to the knowledge base.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404Returned when the knowledge base or document is not found.

One documented failure

  • not_found

    Dataset not found.

    not_found

503Returned on the Dify Cloud Sandbox plan when vector space usage could not be verified; 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 when the document is unavailable for update, doc_form is invalid, or name is missing when text is supplied; a 403 indicates that API access, subscription limits, or API-key scope prevent the operation; a 404 indicates that the knowledge base or document was not found; a 503 indicates that vector space usage could not be verified on the Dify Cloud Sandbox plan. The dataset_id path parameter and document_id path parameter must identify the knowledge base and document to update. doc_form must be text_model, hierarchical_model, or qa_model; process_rule.mode must be automatic, custom, or hierarchical; and retrieval_model.search_method must be keyword_search, semantic_search, full_text_search, or hybrid_search.