Update Document by Text

post/datasets/{dataset_id}/documents/{document_id}/update-by-text

Request example

curl --request POST \
  --url https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}'

import requests

url = "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "doc_form": "text_model",
    "doc_language": "English",
    "name": "<string>",
    "process_rule": {
        "mode": "automatic",
        "rules": {
            "pre_processing_rules": [
                {
                    "enabled": True,
                    "id": "remove_stopwords"
                }
            ],
            "segmentation": {
                "chunk_overlap": 0,
                "max_tokens": 1,
                "separator": "
"
            }
        }
    },
    "retrieval_model": {
        "metadata_filtering_conditions": {
            "conditions": [
                {
                    "comparison_operator": "contains",
                    "name": "<string>",
                    "value": "<string>"
                }
            ],
            "logical_operator": "and"
        },
        "reranking_enable": True,
        "reranking_mode": "reranking_model",
        "reranking_model": {
            "reranking_model_name": "<string>",
            "reranking_provider_name": "<string>"
        },
        "score_threshold": 1,
        "score_threshold_enabled": True,
        "search_method": "keyword_search",
        "top_k": 1,
        "weights": {
            "keyword_setting": {
                "keyword_weight": 1
            },
            "vector_setting": {
                "embedding_model_name": "<string>",
                "embedding_provider_name": "<string>",
                "vector_weight": 1
            },
            "weight_type": "semantic_first"
        }
    },
    "text": "<string>"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "doc_form": "text_model",
    "doc_language": "English",
    "name": "<string>",
    "process_rule": {
      "mode": "automatic",
      "rules": {
        "pre_processing_rules": [
          {
            "enabled": true,
            "id": "remove_stopwords"
          }
        ],
        "segmentation": {
          "chunk_overlap": 0,
          "max_tokens": 1,
          "separator": "\n"
        }
      }
    },
    "retrieval_model": {
      "metadata_filtering_conditions": {
        "conditions": [
          {
            "comparison_operator": "contains",
            "name": "<string>",
            "value": "<string>"
          }
        ],
        "logical_operator": "and"
      },
      "reranking_enable": true,
      "reranking_mode": "reranking_model",
      "reranking_model": {
        "reranking_model_name": "<string>",
        "reranking_provider_name": "<string>"
      },
      "score_threshold": 1,
      "score_threshold_enabled": true,
      "search_method": "keyword_search",
      "top_k": 1,
      "weights": {
        "keyword_setting": {
          "keyword_weight": 1
        },
        "vector_setting": {
          "embedding_model_name": "<string>",
          "embedding_provider_name": "<string>",
          "vector_weight": 1
        },
        "weight_type": "semantic_first"
      }
    },
    "text": "<string>"
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"
	payload := strings.NewReader("{\n  \"doc_form\": \"text_model\",\n  \"doc_language\": \"English\",\n  \"name\": \"<string>\",\n  \"process_rule\": {\n    \"mode\": \"automatic\",\n    \"rules\": {\n      \"pre_processing_rules\": [\n        {\n          \"enabled\": true,\n          \"id\": \"remove_stopwords\"\n        }\n      ],\n      \"segmentation\": {\n        \"chunk_overlap\": 0,\n        \"max_tokens\": 1,\n        \"separator\": \"\\n\"\n      }\n    }\n  },\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"text\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"doc_form\": \"text_model\",\n  \"doc_language\": \"English\",\n  \"name\": \"<string>\",\n  \"process_rule\": {\n    \"mode\": \"automatic\",\n    \"rules\": {\n      \"pre_processing_rules\": [\n        {\n          \"enabled\": true,\n          \"id\": \"remove_stopwords\"\n        }\n      ],\n      \"segmentation\": {\n        \"chunk_overlap\": 0,\n        \"max_tokens\": 1,\n        \"separator\": \"\\n\"\n      }\n    }\n  },\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  },\n  \"text\": \"<string>\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}/update-by-text')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "doc_form": "text_model",
  "doc_language": "English",
  "name": "<string>",
  "process_rule": {
    "mode": "automatic",
    "rules": {
      "pre_processing_rules": [
        {
          "enabled": true,
          "id": "remove_stopwords"
        }
      ],
      "segmentation": {
        "chunk_overlap": 0,
        "max_tokens": 1,
        "separator": "\\n"
      }
    }
  },
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  },
  "text": "<string>"
}'

response = http.request(request)
puts response.read_body

Response

{
  "batch": "20250306150245647595",
  "document": {
    "archived": false,
    "created_at": 1741267200,
    "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
    "created_from": "api",
    "data_source_detail_dict": {
      "upload_file": {
        "created_at": 1741267200,
        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
        "extension": "txt",
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "mime_type": "text/plain",
        "name": "guide.txt",
        "size": 2048
      }
    },
    "data_source_info": {
      "upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "data_source_type": "upload_file",
    "dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
    "disabled_at": null,
    "disabled_by": null,
    "display_status": "available",
    "doc_form": "text_model",
    "doc_metadata": [],
    "enabled": true,
    "error": null,
    "hit_count": 0,
    "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
    "indexing_status": "completed",
    "name": "guide.txt",
    "need_summary": false,
    "position": 1,
    "summary_index_status": null,
    "tokens": 512,
    "word_count": 350
  }
}

{
  "code": "invalid_param",
  "message": "name is required when text is provided.",
  "status": 400
}

{
  "code": "invalid_param",
  "message": "Document is not available",
  "status": 400
}

{
  "code": "provider_not_initialize",
  "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.",
  "status": 400
}

{
  "code": "forbidden",
  "message": "Dataset api access is not enabled.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The capacity of the vector space has reached the limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The API key is not authorized to access this knowledge base.",
  "status": 403
}

{
  "code": "not_found",
  "message": "Dataset not found.",
  "status": 404
}

{
  "code": "not_found",
  "message": "Document not found.",
  "status": 404
}

{
  "code": "service_unavailable",
  "message": "Unable to verify vector space usage right now. Please try again later.",
  "status": 503
}

post/datasets/{dataset_id}/documents/{document_id}/update-by-text

Authorization

Authorizationstringheaderrequired#

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path parameters

dataset_idstringrequired#

Knowledge base ID, from List Knowledge Bases. For a scoped key, copy the ID from the Dify URL.

document_idstringrequired#

Document ID. From List Documents.

Body

application/json

doc_formenum<string>#

text_model for standard text chunking, hierarchical_model for parent-child chunk structure, qa_model for question-answer pair extraction.

Default: "text_model"

Options:text_modelhierarchical_modelqa_model

doc_languagestring#

Language of the document for processing optimization.

Default: "English"

namestring#

Document name. Required when text is provided.

process_ruleobject#

Processing rules for chunking.

Show child attributes

modeenum<string>required#

automatic uses built-in rules, custom allows manual configuration, hierarchical enables parent-child chunk structure (use with doc_form: hierarchical_model).

Options:automaticcustomhierarchical

rulesobject#

Show child attributes

pre_processing_rulesobject[]#

Show child attributes

enabledboolean#

Whether this preprocessing rule is enabled.

idenum<string>#

Rule identifier.

Options:remove_stopwordsremove_extra_spacesremove_urls_emails

segmentationobject#

Show child attributes

chunk_overlapinteger#

Token overlap between chunks.

Default: 0

max_tokensinteger#

Maximum token count per chunk.

separatorstring#

Custom separator for splitting text.

Default: "\n"

retrieval_modelobject#

Show child attributes

metadata_filtering_conditionsobject#

Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.

Show child attributes

conditionsobject[]#

List of metadata conditions to evaluate.

Show child attributes

comparison_operatorenum<string>required#

Comparison to apply, by metadata type:

String or array metadata: contains, not contains, start with, end with, is, is not, empty, not empty, in, not in
Numeric metadata: =, ≠, >, <, ≥, ≤
Time metadata: before, after

Options:containsnot containsstart withend withisis notemptynot emptyinnot in=≠><≥≤beforeafter

namestringrequired#

Metadata field name to compare against.

valuestring · string[] · number#

Value to compare against. Type depends on comparison_operator: string for most string operators, array of strings for in and not in, number for numeric operators, and omitted for empty and not empty.

logical_operatorenum<string>#

How to combine multiple conditions.

Default: "and"

Options:andor

reranking_enablebooleanrequired#

Whether reranking is enabled.

reranking_modeenum<string>#

Reranking mode. Required when reranking_enable is true.

Options:reranking_modelweighted_score

reranking_modelobject#

Reranking model configuration.

Show child attributes

reranking_model_namestring#

Name of the reranking model.

reranking_provider_namestring#

Reranking model provider identifier, formatted as organization/plugin_name/provider_name (e.g. langgenius/cohere/cohere). A bare name like cohere expands to langgenius/<name>/<name> and works only for langgenius-published plugins.

Get valid values from the provider field of Get Available Models with model_type=rerank.

score_thresholdnumber#

Minimum similarity score for results. Only effective when score_threshold_enabled is true.

score_threshold_enabledbooleanrequired#

Whether score threshold filtering is enabled.

search_methodenum<string>required#

Search method used for retrieval.

Options:keyword_searchsemantic_searchfull_text_searchhybrid_search

top_kintegerrequired#

Maximum number of results to return.

weightsobject#

Weight configuration for hybrid search.

Show child attributes

keyword_settingobject#

Keyword search weight settings.

Show child attributes

keyword_weightnumber#

Weight assigned to keyword search results.

vector_settingobject#

Semantic search weight settings.

Show child attributes

embedding_model_namestring#

Name of the embedding model used for vector search.

embedding_provider_namestring#

Provider of the embedding model used for vector search.

vector_weightnumber#

Weight assigned to semantic (vector) search results.

weight_typeenum<string>#

Strategy for balancing semantic and keyword search weights.

Options:semantic_firstkeyword_firstcustomized

textstring#

Document text content.

Responses

application/json

Document updated successfully.

batchstring#

Batch ID for tracking indexing progress.

documentobject#

Show child attributes

archivedboolean#

Whether the document is archived.

created_atnumber#

Creation timestamp (Unix epoch in seconds).

created_bystring#

ID of the user who created the document.

created_fromstring#

Origin of the document. api for API creation, web for UI creation.

data_source_detail_dictobject#

Detailed data source information including file details.

data_source_infoobject#

Raw data source information, varies by data_source_type.

data_source_typestring#

How the document was created. upload_file for file uploads, notion_import for Notion imports.

dataset_process_rule_idstring#

ID of the processing rule applied to this document.

disabled_atnumber#

Timestamp when the document was disabled. null if enabled.

disabled_bystring#

ID of the user who disabled the document. null if enabled.

display_statusstring#

User-facing display status derived from indexing_status and enabled state.

doc_formstring#

Document chunking mode. text_model for standard text chunking, hierarchical_model for parent-child structure, qa_model for QA pair extraction.

doc_metadataobject[]#

Metadata values assigned to this document.

Show child attributes

idstring#

Metadata field identifier.

namestring#

Metadata field name.

typestring#

Metadata field value type.

valuestring#

Metadata value for this document.

enabledboolean#

Whether the document is enabled for retrieval.

errorstring#

Error message if indexing failed. null when no error.

hit_countinteger#

Number of times the document has been matched in retrieval queries.

idstring#

Unique identifier of the document.

indexing_statusstring#

Current indexing status. waiting for queued, parsing while extracting content, cleaning while removing noise, splitting while chunking, indexing while building vectors, completed when ready, error if failed, paused if manually paused.

namestring#

Document name.

need_summaryboolean#

Whether a summary needs to be generated for this document.

positioninteger#

Display position of the document in the list.

summary_index_statusstring#

Status of the summary index for this document. null if summary indexing is not configured.

tokensinteger#

Total number of tokens in the document.

word_countinteger#

Total word count of the document.

Get Document Indexing Status Update Document by File