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

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://raw.githubusercontent.com/api-evangelist/dify/refs/heads/main/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"

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.

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://raw.githubusercontent.com/api-evangelist/dify/refs/heads/main/openapi/dify-documents-api-openapi.yml