---
title: "Create Document by File"
method: POST
path: "/datasets/{dataset_id}/document/create-by-file"
tags: ["Documents"]
---

# Create Document by File

`POST /datasets/{dataset_id}/document/create-by-file`

Creates a document in a knowledge base from an uploaded file. Common formats such as PDF, TXT, and DOCX are supported. Indexing runs asynchronously; track it with the returned `batch` ID via [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status).

## Path parameters

- `dataset_id` string, uuid, required

## Response `200`

Document created successfully.

- object
  - `document` Document
    - `id` string — Unique identifier of the document.
    - `position` integer — Display position of the document in the list.
    - `data_source_type` string — How the document was created. `upload_file` for file uploads, `notion_import` for Notion imports.
    - `data_source_info` object — Raw data source information, varies by `data_source_type`.
    - `data_source_detail_dict` object — Detailed data source information including file details.
    - `dataset_process_rule_id` string — ID of the processing rule applied to this document.
    - `name` string — Document name.
    - `created_from` string — Origin of the document. `api` for API creation, `web` for UI creation.
    - `created_by` string — ID of the user who created the document.
    - `created_at` number — Creation timestamp (Unix epoch in seconds).
    - `tokens` integer — Total number of tokens in the document.
    - `indexing_status` string — 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.
    - `error` string, nullable — Error message if indexing failed. `null` when no error.
    - `enabled` boolean — Whether the document is enabled for retrieval.
    - `disabled_at` number, nullable — Timestamp when the document was disabled. `null` if enabled.
    - `disabled_by` string, nullable — ID of the user who disabled the document. `null` if enabled.
    - `archived` boolean — Whether the document is archived.
    - `display_status` string — User-facing display status derived from `indexing_status` and `enabled` state.
    - `word_count` integer — Total word count of the document.
    - `hit_count` integer — Number of times the document has been matched in retrieval queries.
    - `doc_form` string — Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction.
    - `doc_metadata` object[] — Metadata values assigned to this document.
      - `id` string — Metadata field identifier.
      - `name` string — Metadata field name.
      - `type` string — Metadata field value type.
      - `value` string — Metadata value for this document.
    - `summary_index_status` string, nullable — Status of the summary index for this document. `null` if summary indexing is not configured.
    - `need_summary` boolean — Whether a summary needs to be generated for this document.
  - `batch` string — Batch ID for tracking indexing progress.

## Other responses

- `400` — - `no_file_uploaded` : No file was provided in the request. - `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 knowledge base is external, `indexing_technique` is required, or `process_rule` is missing.
- `403` — - `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` — `not_found` : Knowledge base not found.

---

[API](https://skmtc.net/langgenius/apis/dify-service-api.md) · [All operations](https://skmtc.net/langgenius/apis/dify-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langgenius/dify-service-api/versions/361dc12484f4/schema)