> ## Documentation Index > Fetch the complete documentation index at: https://dify-6c0370d8-fix-template-upload-size-guidance.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create Document by Text > Creates a document in a knowledge base from raw text. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status). ## OpenAPI ````yaml /en/api-reference/openapi_service.json post /datasets/{dataset_id}/document/create-by-text openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline paths: /datasets/{dataset_id}/document/create-by-text: post: tags: - Documents summary: Create Document by Text description: >- Creates a document in a knowledge base from raw text. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status). operationId: createDocumentFromText parameters: - description: >- Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). in: path name: dataset_id required: true schema: format: uuid type: string requestBody: content: application/json: schema: properties: doc_form: default: text_model description: >- `text_model` for standard text chunking, `hierarchical_model` for parent-child chunk structure, `qa_model` for question-answer pair extraction. enum: - text_model - hierarchical_model - qa_model type: string doc_language: default: English description: Language of the document for processing optimization. type: string embedding_model: description: >- Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`. type: string embedding_model_provider: description: >- Embedding model provider. Use the `provider` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`. type: string indexing_technique: description: >- 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. enum: - high_quality - economy type: string name: description: Document name. type: string original_document_id: description: >- Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents). type: string process_rule: description: Processing rules for chunking. properties: mode: description: >- `automatic` uses built-in rules, `custom` allows manual configuration, `hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`). enum: - automatic - custom - hierarchical type: string rules: properties: pre_processing_rules: items: properties: enabled: description: Whether this preprocessing rule is enabled. type: boolean id: description: Rule identifier. enum: - remove_stopwords - remove_extra_spaces - remove_urls_emails type: string type: object type: array segmentation: properties: chunk_overlap: default: 0 description: Token overlap between chunks. type: integer max_tokens: description: Maximum token count per chunk. type: integer separator: default: |+ description: Custom separator for splitting text. type: string type: object type: object required: - mode type: object retrieval_model: $ref: '#/components/schemas/RetrievalModel' description: >- Controls how chunks are searched and ranked when querying this knowledge base. text: description: Document text content. type: string required: - name - text type: object required: true responses: '200': content: application/json: examples: success: summary: Response Example value: 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: indexing doc_form: text_model doc_metadata: [] enabled: true error: null hit_count: 0 id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac indexing_status: indexing name: guide.txt need_summary: false position: 1 summary_index_status: null tokens: 0 word_count: 0 schema: properties: batch: description: Batch ID for tracking indexing progress. type: string document: $ref: '#/components/schemas/Document' type: object description: Document created successfully. '400': content: application/json: examples: invalid_param_indexing: summary: invalid_param (indexing_technique) value: code: invalid_param message: indexing_technique is required. status: 400 provider_not_initialize: summary: provider_not_initialize value: code: provider_not_initialize message: >- No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. status: 400 description: >- - `provider_not_initialize` : No model provider credentials are configured for the workspace. - `invalid_param` : `indexing_technique` is required when adding the first document, or `doc_form` is invalid. '403': content: application/json: examples: forbidden_1: summary: forbidden (api access) value: code: forbidden message: Dataset api access is not enabled. status: 403 forbidden_2: summary: forbidden (vector space) value: code: forbidden message: >- The capacity of the vector space has reached the limit of your subscription. status: 403 forbidden_3: summary: forbidden (documents limit) value: code: forbidden message: >- The number of documents has reached the limit of your subscription. status: 403 forbidden_4: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 description: >- - `forbidden` : Knowledge base API access is not enabled. - `forbidden` : The capacity of the vector space has reached the limit of your subscription. - `forbidden` : The number of documents has reached the limit of your subscription. - `forbidden` : Sorry, you have reached the knowledge base request rate limit of your subscription. '404': content: application/json: examples: not_found: summary: not_found value: code: not_found message: Dataset not found. status: 404 description: '`not_found` : Knowledge base not found.' '503': content: application/json: examples: service_unavailable: summary: service_unavailable value: code: service_unavailable message: >- Unable to verify vector space usage right now. Please try again later. status: 503 description: >- `service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later. components: schemas: RetrievalModel: properties: metadata_filtering_conditions: description: >- Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields. nullable: true properties: conditions: description: List of metadata conditions to evaluate. items: properties: comparison_operator: description: >- 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` enum: - contains - not contains - start with - end with - is - is not - empty - not empty - in - not in - '=' - ≠ - '>' - < - ≥ - ≤ - before - after type: string name: description: Metadata field name to compare against. type: string value: description: >- 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`. nullable: true oneOf: - type: string - items: type: string type: array - type: number required: - name - comparison_operator type: object nullable: true type: array logical_operator: default: and description: How to combine multiple conditions. enum: - and - or nullable: true type: string type: object reranking_enable: description: Whether reranking is enabled. type: boolean reranking_mode: description: Reranking mode. Required when `reranking_enable` is `true`. enum: - reranking_model - weighted_score nullable: true type: string reranking_model: description: Reranking model configuration. properties: reranking_model_name: description: Name of the reranking model. type: string reranking_provider_name: description: >- Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius//` and works only for langgenius-published plugins. Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`. type: string type: object score_threshold: description: >- Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`. nullable: true type: number score_threshold_enabled: description: Whether score threshold filtering is enabled. type: boolean search_method: description: Search method used for retrieval. enum: - keyword_search - semantic_search - full_text_search - hybrid_search type: string top_k: description: Maximum number of results to return. type: integer weights: description: Weight configuration for hybrid search. nullable: true properties: keyword_setting: description: Keyword search weight settings. properties: keyword_weight: description: Weight assigned to keyword search results. type: number type: object vector_setting: description: Semantic search weight settings. properties: embedding_model_name: description: Name of the embedding model used for vector search. type: string embedding_provider_name: description: Provider of the embedding model used for vector search. type: string vector_weight: description: Weight assigned to semantic (vector) search results. type: number type: object weight_type: description: Strategy for balancing semantic and keyword search weights. enum: - semantic_first - keyword_first - customized type: string type: object required: - search_method - reranking_enable - top_k - score_threshold_enabled type: object Document: properties: archived: description: Whether the document is archived. type: boolean created_at: description: Creation timestamp (Unix epoch in seconds). type: number created_by: description: ID of the user who created the document. type: string created_from: description: >- Origin of the document. `api` for API creation, `web` for UI creation. type: string data_source_detail_dict: description: Detailed data source information including file details. type: object data_source_info: description: Raw data source information, varies by `data_source_type`. type: object data_source_type: description: >- How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports. type: string dataset_process_rule_id: description: ID of the processing rule applied to this document. type: string disabled_at: description: Timestamp when the document was disabled. `null` if enabled. nullable: true type: number disabled_by: description: ID of the user who disabled the document. `null` if enabled. nullable: true type: string display_status: description: >- User-facing display status derived from `indexing_status` and `enabled` state. type: string doc_form: description: >- Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction. type: string doc_metadata: description: Metadata values assigned to this document. items: properties: id: description: Metadata field identifier. type: string name: description: Metadata field name. type: string type: description: Metadata field value type. type: string value: description: Metadata value for this document. type: string type: object type: array enabled: description: Whether the document is enabled for retrieval. type: boolean error: description: Error message if indexing failed. `null` when no error. nullable: true type: string hit_count: description: Number of times the document has been matched in retrieval queries. type: integer id: description: Unique identifier of the document. type: string indexing_status: description: >- 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. type: string name: description: Document name. type: string need_summary: description: Whether a summary needs to be generated for this document. type: boolean position: description: Display position of the document in the list. type: integer summary_index_status: description: >- Status of the summary index for this document. `null` if summary indexing is not configured. nullable: true type: string tokens: description: Total number of tokens in the document. type: integer word_count: description: Total word count of the document. type: integer type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 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](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ````