Dify

Dify Documents API

Operations for creating, updating, and managing documents within a knowledge base. 12 operation(s) from the Dify Service API.

GitHub OpenAPI
Business capability
Retrieval & Embeddings AE-110.60

Operations 12

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /datasets/{dataset_id}/document/create-by-text Add a document to a knowledge base from raw text · Create Document by Text #
Ask an LLM
“How do I add pasted text as a new document in my Dify knowledge base?”
“Can I choose parent-child or Q&A chunking when creating a document from text?”
Tell an agent
Create a document named {name} in knowledge base {dataset_id} from the text {text}.
Add text {text} as document {name} to {dataset_id} using {indexing_technique} indexing.
POST /datasets/{dataset_id}/document/create-by-file Add a document to a knowledge base from a file · Create Document by File #
Ask an LLM
“Can I upload a PDF or DOCX straight into a knowledge base as a new document?”
“What is the maximum file size for creating a knowledge base document from an upload?”
Tell an agent
Upload {file} as a new document in knowledge base {dataset_id}.
Create a knowledge base document in {dataset_id} from file {file} with settings {data}.
GET /datasets/{dataset_id}/documents List the documents in a knowledge base · List Documents #
Ask an LLM
“Which documents are in my knowledge base?”
“Can I filter a knowledge base's documents by name or display status?”
Tell an agent
List the documents in knowledge base {dataset_id}.
Find documents in {dataset_id} whose name matches {keyword}.
GET /datasets/{dataset_id}/documents/{document_id} Get details of a single knowledge base document · Get Document #
Ask an LLM
“What are the details and metadata of one document in my knowledge base?”
“Can I fetch only a document's metadata without the other fields?”
Tell an agent
Show document {document_id} in knowledge base {dataset_id}.
Get document {document_id} of {dataset_id} with metadata mode {metadata}.
DELETE /datasets/{dataset_id}/documents/{document_id} Delete a document and all its chunks · Delete Document #
Ask an LLM
“How do I permanently remove a document from a knowledge base?”
“Are a document's chunks deleted too when I delete the document?”
Tell an agent destructive · confirm first
Delete document {document_id} from knowledge base {dataset_id}.
Permanently remove document {document_id} and its chunks from {dataset_id}.
PATCH /datasets/{dataset_id}/documents/{document_id} Replace a document's file and re-index it · Update Document #
Ask an LLM
“What is the recommended way to replace a document with a newer version of its file?”
“Can I swap the uploaded file behind an existing document and have it re-indexed?”
Tell an agent
Replace document {document_id} in {dataset_id} with the new file {file}.
Use the current file-update endpoint to upload {file} over document {document_id} in knowledge base {dataset_id}.
GET /datasets/{dataset_id}/documents/{document_id}/download Get a download link for a document's original file · Download Document #
Ask an LLM
“How do I download the original file I uploaded for a single document?”
“Can I get a signed URL to one knowledge base document's source file?”
Tell an agent
Get a download link for the original file of document {document_id} in {dataset_id}.
Give me a signed URL for document {document_id} from knowledge base {dataset_id}.
GET /datasets/{dataset_id}/documents/{batch}/indexing-status Check indexing progress for a batch of documents · Get Document Indexing Status #
Ask an LLM
“Has my newly uploaded document finished indexing yet?”
“Which stage is each document in a batch at, and how many chunks are done?”
Tell an agent
Check indexing status for batch {batch} in knowledge base {dataset_id}.
Tell me when every document in batch {batch} of {dataset_id} is completed or errored.
POST /datasets/{dataset_id}/documents/{document_id}/update-by-text Update a document's text, name or chunking rules · Update Document by Text #
Ask an LLM
“Can I edit the text content of a document that was created from text?”
“Is it possible to rename a document or change its chunking rules without uploading a file?”
Tell an agent
Replace the text of document {document_id} in {dataset_id} with {text} and name it {name}.
Change the chunking process rules of document {document_id} in knowledge base {dataset_id} to {process_rule}.
POST /datasets/{dataset_id}/documents/{document_id}/update-by-file Replace a document's file (deprecated endpoint) · Update Document by File #
Ask an LLM
“Is the older update-by-file endpoint for documents still supported?”
“My integration uses the deprecated update-by-file call; how does it re-index a document?”
Tell an agent
Use the deprecated update-by-file endpoint to upload {file} over document {document_id} in {dataset_id}.
Call the legacy update-by-file route for document {document_id} in knowledge base {dataset_id}.
POST /datasets/{dataset_id}/documents/download-zip Download several documents as one ZIP · Download Documents as ZIP #
Ask an LLM
“Can I download multiple uploaded documents at once as a ZIP archive?”
“Why are documents I created from pasted text missing from my ZIP download?”
Tell an agent
Bundle documents {document_ids} from knowledge base {dataset_id} into a ZIP.
Download a ZIP archive of the files for documents {document_ids} in {dataset_id}.
PATCH /datasets/{dataset_id}/documents/status/{action} Enable, disable or archive documents in bulk · Update Document Status in Batch #
Ask an LLM
“How do I disable several documents so they stop being used in retrieval?”
“Can I archive or unarchive a group of documents in one request?”
Tell an agent
Apply {action} to documents {document_ids} in knowledge base {dataset_id}.
Archive documents {document_ids} in {dataset_id} using action {action}.

Documentation

📖
APIReference
https://docs.dify.ai/en/api-reference/documents/list-documents

Specifications

⚙
OpenAPI
https://artifacts.apis.io/dify/openapi/dify-documents-api-openapi.yml

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.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/dify:dify-documents-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

dify-documents-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Dify Service 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:


# --- truncated at 32 KB (93 KB total) ---
# Full source: https://artifacts.apis.io/dify/openapi/dify-documents-api-openapi.yml