Dify Octri Demo
POST/datasets/{dataset_id}/document/create-by-text

Create a knowledge base document from text

Creates a document in a knowledge base from raw text. Provide name and text; when adding the first document, also provide indexing_technique, and doc_form defaults to text_model. Indexing runs asynchronously, so use the returned batch ID with GET /datasets/{dataset_id}/documents/{batch}/indexing-status to track progress.

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

1 parameter · 10 body fields
dataset_idstringrequired
The UUID of the knowledge base where you want to create the document.

Document creation settings and raw text content. name and text are required; provide indexing_technique when adding the first document to a knowledge base.

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
embedding_modelstringoptional
Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.
embedding_model_providerstringoptional
Embedding model provider. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.
indexing_techniquestringoptional
Required when adding the first document to a knowledge base. Subsequent documents inherit the knowledge base's indexing technique if omitted. `high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.
Allowed:high_qualityeconomy
namestringrequired
Document name.
original_document_idstringoptional
Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents).
process_ruleobjectoptional
Processing rules for chunking.
retrieval_modelobjectoptional
Retrieval configuration, including required `search_method`, `reranking_enable`, `top_k`, and `score_threshold_enabled` settings. `search_method` can be `keyword_search`, `semantic_search`, `full_text_search`, or `hybrid_search`; when `reranking_enable` is true, `reranking_mode` is required and can be `reranking_model` or `weighted_score`.
textstringrequired
Document text content.

5 status codes
200Returns the created document object and a `batch` ID for tracking indexing progress.
batchstringoptional
Batch ID for tracking indexing progress.
documentobjectoptional
400Returned when the workspace has no configured default embedding model, or when `indexing_technique` is missing for the first document or `doc_form` is invalid.

2 documented failures

  • invalid_param

    indexing_technique is required.

    invalid_param (indexing_technique)

  • 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 capacity, document-count, or request-rate limit is reached, or the API key is not scoped to the specified knowledge base.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404Returned when the knowledge base does not exist.

One documented failure

  • not_found

    Dataset not found.

    not_found

503Returned on the Dify Cloud Sandbox plan when vector space usage cannot 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 first document lacks indexing_technique, doc_form is invalid, or the workspace has no configured default embedding model. A 403 is returned when knowledge base API access is disabled, a subscription limit or request rate limit is reached, or the API key is not scoped to the specified knowledge base; a 404 is returned when the knowledge base does not exist. A 503 can occur on the Dify Cloud Sandbox plan when vector space usage cannot be verified; retry the request. The dataset_id path parameter must identify an accessible knowledge base; name and text are required, and doc_form, indexing_technique, process_rule.mode, and retrieval_model.search_method must use the values allowed by their schemas.