Dify Documents API
Operations for creating, updating, and managing documents within a knowledge base. 12 operation(s) from the Dify Service API.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/dify-documents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.0.1
info:
title: Dify Documents API
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.
version: 1.0.0
servers:
- url: https://{api_base_url}
description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own
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:
- name: Documents
description: Operations for creating, updating, and managing documents within a knowledge base.
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:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- text
properties:
name:
type: string
description: Document name.
text:
type: string
description: Document text content.
indexing_technique:
type: string
enum:
- high_quality
- economy
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.
doc_form:
type: string
enum:
- text_model
- hierarchical_model
- qa_model
default: text_model
description: '`text_model` for standard text chunking, `hierarchical_model` for parent-child
chunk structure, `qa_model` for question-answer pair extraction.'
doc_language:
type: string
default: English
description: Language of the document for processing optimization.
process_rule:
type: object
description: Processing rules for chunking.
required:
- mode
properties:
mode:
type: string
enum:
- automatic
- custom
- hierarchical
description: '`automatic` uses built-in rules, `custom` allows manual configuration,
`hierarchical` enables parent-child chunk structure (use with `doc_form: hierarchical_model`).'
rules:
type: object
properties:
pre_processing_rules:
type: array
items:
type: object
properties:
id:
type: string
enum:
- remove_stopwords
- remove_extra_spaces
- remove_urls_emails
description: Rule identifier.
enabled:
type: boolean
description: Whether this preprocessing rule is enabled.
segmentation:
type: object
properties:
separator:
type: string
default: '
'
description: Custom separator for splitting text.
max_tokens:
type: integer
description: Maximum token count per chunk.
chunk_overlap:
type: integer
default: 0
description: Token overlap between chunks.
retrieval_model:
$ref: '#/components/schemas/RetrievalModel'
description: Controls how chunks are searched and ranked when querying this knowledge
base.
embedding_model:
type: string
description: 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_provider:
type: string
description: Embedding model provider. Use the `provider` field from [Get Available
Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.
original_document_id:
type: string
description: Original document ID for versioning. Get it from [List Documents](/en/api-reference/documents/list-documents).
responses:
'200':
description: Document created successfully.
content:
application/json:
schema:
type: object
properties:
document:
$ref: '#/components/schemas/Document'
batch:
type: string
description: Batch ID for tracking indexing progress.
examples:
success:
summary: Response Example
value:
document:
id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
position: 1
data_source_type: upload_file
data_source_info:
upload_file_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
data_source_detail_dict:
upload_file:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: guide.txt
size: 2048
extension: txt
mime_type: text/plain
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
dataset_process_rule_id: e1f2a3b4-c5d6-7890-ef12-345678901234
name: guide.txt
created_from: api
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
tokens: 0
indexing_status: indexing
error: null
enabled: true
disabled_at: null
disabled_by: null
archived: false
display_status: indexing
word_count: 0
hit_count: 0
doc_form: text_model
doc_metadata: []
summary_index_status: null
need_summary: false
batch: '20250306150245647595'
'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.'
content:
application/json:
examples:
provider_not_initialize:
summary: provider_not_initialize
value:
status: 400
code: provider_not_initialize
message: No valid model provider credentials found. Please go to Settings -> Model
Provider to complete your provider credentials.
invalid_param_indexing:
summary: invalid_param (indexing_technique)
value:
status: 400
code: invalid_param
message: indexing_technique is required.
'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.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (vector space)
value:
status: 403
code: forbidden
message: The capacity of the vector space has reached the limit of your subscription.
forbidden_3:
summary: forbidden (documents limit)
value:
status: 403
code: forbidden
message: The number of documents has reached the limit of your subscription.
forbidden_4:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Knowledge base not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
'503':
description: '`service_unavailable` : Vector space usage could not be verified. Returned on
the Dify Cloud Sandbox plan only; retry the request later.'
content:
application/json:
examples:
service_unavailable:
summary: service_unavailable
value:
status: 503
code: service_unavailable
message: Unable to verify vector space usage right now. Please try again later.
x-mint:
href: /en/api-reference/documents/create-document-by-text
metadata:
title: Create Document by Text
sidebarTitle: Create Document by Text
/datasets/{dataset_id}/document/create-by-file:
post:
tags:
- Documents
summary: Create Document by File
description: 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).
operationId: createDocumentFromFile
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: '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.'
data:
type: string
description: 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`.
example: '{"indexing_technique":"high_quality","doc_form":"text_model","doc_language":"English","process_rule":{"mode":"automatic"}}'
responses:
'200':
description: Document created successfully.
content:
application/json:
schema:
type: object
properties:
document:
$ref: '#/components/schemas/Document'
batch:
type: string
description: Batch ID for tracking indexing progress.
examples:
success:
summary: Response Example
value:
document:
id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
position: 1
data_source_type: upload_file
data_source_info:
upload_file_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
data_source_detail_dict:
upload_file:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: guide.txt
size: 2048
extension: txt
mime_type: text/plain
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
dataset_process_rule_id: e1f2a3b4-c5d6-7890-ef12-345678901234
name: guide.txt
created_from: api
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
tokens: 0
indexing_status: indexing
error: null
enabled: true
disabled_at: null
disabled_by: null
archived: false
display_status: indexing
word_count: 0
hit_count: 0
doc_form: text_model
doc_metadata: []
summary_index_status: null
need_summary: false
batch: '20250306150245647595'
'400':
description: '- `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.'
content:
application/json:
examples:
no_file_uploaded:
summary: no_file_uploaded
value:
status: 400
code: no_file_uploaded
message: Please upload your file.
too_many_files:
summary: too_many_files
value:
status: 400
code: too_many_files
message: Only one file is allowed.
filename_not_exists_error:
summary: filename_not_exists_error
value:
status: 400
code: filename_not_exists_error
message: The specified filename does not exist.
provider_not_initialize:
summary: provider_not_initialize
value:
status: 400
code: provider_not_initialize
message: No valid model provider credentials found. Please go to Settings -> Model
Provider to complete your provider credentials.
invalid_param_external:
summary: invalid_param (external)
value:
status: 400
code: invalid_param
message: External datasets are not supported.
'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.'
content:
application/json:
examples:
forbidden_1:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
forbidden_2:
summary: forbidden (vector space)
value:
status: 403
code: forbidden
message: The capacity of the vector space has reached the limit of your subscription.
forbidden_3:
summary: forbidden (documents limit)
value:
status: 403
code: forbidden
message: The number of documents has reached the limit of your subscription.
forbidden_4:
summary: forbidden (rate limit)
value:
status: 403
code: forbidden
message: Sorry, you have reached the knowledge base request rate limit of your subscription.
'404':
description: '`not_found` : Knowledge base not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
'413':
description: '`file_too_large` : The uploaded file exceeds the maximum size.'
content:
application/json:
examples:
file_too_large:
summary: file_too_large
value:
status: 413
code: file_too_large
message: File size exceeded.
'503':
description: '`service_unavailable` : Vector space usage could not be verified. Returned on
the Dify Cloud Sandbox plan only; retry the request later.'
content:
application/json:
examples:
service_unavailable:
summary: service_unavailable
value:
status: 503
code: service_unavailable
message: Unable to verify vector space usage right now. Please try again later.
x-mint:
href: /en/api-reference/documents/create-document-by-file
metadata:
title: Create Document by File
sidebarTitle: Create Document by File
/datasets/{dataset_id}/documents:
get:
tags:
- Documents
summary: List Documents
description: Returns a paginated list of documents in a knowledge base.
operationId: listDocuments
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: page
in: query
schema:
type: integer
default: 1
description: Page number.
- name: limit
in: query
schema:
type: integer
default: 20
description: Number of items per page. Server caps at `100`.
- name: keyword
in: query
schema:
type: string
description: Search keyword to filter by document name.
- name: status
in: query
schema:
type: string
enum:
- queuing
- indexing
- paused
- error
- available
- disabled
- archived
description: Filter by display status.
responses:
'200':
description: List of documents.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: Array of document objects.
items:
$ref: '#/components/schemas/Document'
has_more:
type: boolean
description: Whether more items exist on the next page.
limit:
type: integer
description: Number of items per page.
total:
type: integer
description: Total number of matching items.
page:
type: integer
description: Current page number.
examples:
success:
summary: Response Example
value:
data:
- id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
position: 1
data_source_type: upload_file
data_source_info:
upload_file_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
data_source_detail_dict:
upload_file:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: guide.txt
size: 2048
extension: txt
mime_type: text/plain
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
dataset_process_rule_id: e1f2a3b4-c5d6-7890-ef12-345678901234
name: guide.txt
created_from: api
created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
created_at: 1741267200
tokens: 512
indexing_status: completed
error: null
enabled: true
disabled_at: null
disabled_by: null
archived: false
display_status: available
word_count: 350
hit_count: 0
doc_form: text_model
doc_metadata: []
summary_index_status: null
need_summary: false
has_more: false
limit: 20
total: 1
page: 1
'403':
description: '`forbidden` : Knowledge base API access is not enabled.'
content:
application/json:
examples:
forbidden:
summary: forbidden (api access)
value:
status: 403
code: forbidden
message: Dataset api access is not enabled.
'404':
description: '`not_found` : Knowledge base not found.'
content:
application/json:
examples:
not_found:
summary: not_found
value:
status: 404
code: not_found
message: Dataset not found.
x-mint:
href: /en/api-reference/documents/list-documents
metadata:
title: List Documents
sidebarTitle: List Documents
/datasets/{dataset_id}/documents/{document_id}:
get:
tags:
- Documents
summary: Get Document
description: Returns detailed information for a single document.
operationId: getDocumentDetail
parameters:
- name: dataset_id
in: path
required: true
schema:
type: string
format: uuid
description: Knowledge base ID. From [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
- name: document_id
in: path
required: true
schema:
type: string
format: uuid
description: Document ID. From [List Documents](/en/api-reference/documents/list-documents).
- name: metadata
in: query
schema:
type: string
enum:
- all
- only
- without
default: all
description: '`all` returns all fields including metadata. `only` returns only `id`, `doc_type`,
and `doc_metadata`. `without` returns all fields except `doc_metadata`.'
responses:
'200':
description: Document details. The returned fields depend on the `metadata` query parameter.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Document identifier.
position:
type: integer
description: Position index within the knowledge base.
data_source_type:
type: string
description: How the document was uploaded. `upload_file` for file uploads, `notion_import`
for Notion imports.
data_source_info:
type: object
description: Data source details. For file uploads, this detail endpoint returns the
full file object under `upload_file` (the list endpoint returns only `upload_file_id`).
properties:
upload_file:
type: object
description: Uploaded file details. Present when `data_source_type` is `upload_file`.
properties:
id:
type: string
description: File identifier.
name:
type: string
description: Original file name.
size:
type: integer
description: File size in bytes.
extension:
type: string
description: File extension.
mime_type:
type: string
description: File MIME type.
created_by:
type: string
description: ID of the user who uploaded the file.
created_at:
type: integer
description: Unix timestamp of file upload.
dataset_process_rule_id:
type: string
description: ID of the processing rule applied to this document.
dataset_process_rule:
type: object
description: Knowledge-base-level processing rule configuration.
document_process_rule:
type: object
description: Document-level processing rule configuration.
name:
type: string
description: Document name.
created_from:
type: string
description: Origin of the document. `api` for API creation, `web` for UI creation.
created_by:
type: string
description: ID of the user who created the document.
created_at:
type: number
description: Unix timestamp of document creation.
tokens:
type: integer
description: Number of tokens in the document.
indexing_status:
type: string
description: Current indexing status, e.g. `waiting`, `parsing`, `cleaning`, `splitting`,
`indexing`, `completed`, `error`, `paused`.
error:
type: string
nullable: true
description: Error message if indexing failed, `null` otherwise.
enabled:
type: boolean
description: Whether the document is enabled for retrieval.
disabled_at:
type: number
nullable: true
description: Unix timestamp when the document was disabled, `null` if enabled.
disabled_by:
type: string
nullable: true
description: ID of the user who disabled the document, `null` if enabled.
archived:
type: boolean
description: Whether the document is archived.
display_status:
type: string
description: Display-friendly indexing status for the UI.
hit_count:
type: integer
description: Number of times this document has been retrieved.
doc_form:
type: string
description: Document chunking mode. `text_model` for standard text, `hierarchical_model`
for parent-child, `qa_model` for QA pairs.
doc_language:
type: string
description: Language of the document content.
doc_type:
type: string
nullable: true
description: Document type classification, `null` if not set.
doc_metadata:
type: array
description: Custom metadata key-value pairs for this document.
items:
type: object
properties:
id:
type: string
description: Metadata field identifier.
name:
type: string
description: Metadata field name.
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dify/refs/heads/main/openapi/dify-documents-api-openapi.yml