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

Create Document 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.

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

1 parameter · 2 body fields
dataset_idstringrequired
Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases). For a scoped key, [copy the ID from the Dify URL](/en/api-reference/guides/knowledge#knowledge-base-id).
datastringoptional
JSON string containing configuration. Accepts the same fields as [Create Document by Text](/en/api-reference/documents/create-document-by-text) (`indexing_technique`, `doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, `embedding_model_provider`) except `name` and `text`.
filestringrequired
File to upload, capped at 15 MB by default. Self-hosted deployments adjust the limit with the `UPLOAD_FILE_SIZE_LIMIT` [environment variable](/en/self-host/deploy/configuration/environments). On Dify Cloud, Professional and Team plans raise the cap to 50 MB.

6 status codes
200Document created successfully.
batchstringoptional
Batch ID for tracking indexing progress.
documentobjectoptional
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` : The workspace has no default embedding model, or the default one has no credentials configured. - `invalid_param` : The knowledge base is external, `indexing_technique` is required, or `process_rule` is missing.

5 documented failures

  • filename_not_exists_error

    The specified filename does not exist.

    filename_not_exists_error

  • invalid_param

    External datasets are not supported.

    invalid_param (external)

  • no_file_uploaded

    Please upload your file.

    no_file_uploaded

  • provider_not_initialize

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

    provider_not_initialize

  • too_many_files

    Only one file is allowed.

    too_many_files

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. - `forbidden` : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them.

One documented failure

  • forbidden

    Dataset api access is not enabled.

    forbidden (api access)

404`not_found` : Knowledge base not found.

One documented failure

  • not_found

    Dataset not found.

    not_found

413`file_too_large` : The uploaded file exceeds the maximum size.

One documented failure

  • file_too_large

    File size exceeded.

    file_too_large

503`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; 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: - 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 : The workspace has no default embedding model, or the default one has no credentials configured.
  • invalid_param : The knowledge base is external, indexing_technique is required, or process_rule is missing. A 403 is returned: - 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.
  • forbidden : The API key is scoped to specific knowledge bases, and this knowledge base is not one of them. A 404 is returned: not_found : Knowledge base not found. A 413 is returned: file_too_large : The uploaded file exceeds the maximum size. A 503 is returned: service_unavailable : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox plan only; retry the request later.