List Documents
Returns a paginated list of documents in a knowledge base.
1 min read
get/datasets/{dataset_id}/documents
Request example
curl --request GET \
--url https://api.dify.ai/v1/datasets/{dataset_id}/documents \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/datasets/{dataset_id}/documents"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/documents', {
method: 'GET',
headers: {
'Authorization': 'Bearer <token>'
}
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/documents',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.dify.ai/v1/datasets/{dataset_id}/documents"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/documents"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/documents')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyResponse
{
"data": [
{
"archived": false,
"created_at": 1741267200,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_from": "api",
"data_source_detail_dict": {
"upload_file": {
"created_at": 1741267200,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"extension": "txt",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"mime_type": "text/plain",
"name": "guide.txt",
"size": 2048
}
},
"data_source_info": {
"upload_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data_source_type": "upload_file",
"dataset_process_rule_id": "e1f2a3b4-c5d6-7890-ef12-345678901234",
"disabled_at": null,
"disabled_by": null,
"display_status": "available",
"doc_form": "text_model",
"doc_metadata": [],
"enabled": true,
"error": null,
"hit_count": 0,
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"indexing_status": "completed",
"name": "guide.txt",
"need_summary": false,
"position": 1,
"summary_index_status": null,
"tokens": 512,
"word_count": 350
}
],
"has_more": false,
"limit": 20,
"page": 1,
"total": 1
}{
"code": "forbidden",
"message": "Dataset api access is not enabled.",
"status": 403
}{
"code": "forbidden",
"message": "The API key is not authorized to access this knowledge base.",
"status": 403
}{
"code": "not_found",
"message": "Dataset not found.",
"status": 404
}get/datasets/{dataset_id}/documents
Authorization
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Path parameters
Knowledge base ID, from List Knowledge Bases. For a scoped key, copy the ID from the Dify URL.
Query parameters
Search keyword to filter by document name.
Filter by display status.
Options:
queuingindexingpausederroravailabledisabledarchivedResponses
application/json
List of documents.
Array of document objects.
Show child attributesHide child attributes
Whether the document is archived.
Creation timestamp (Unix epoch in seconds).
ID of the user who created the document.
Origin of the document.
api for API creation, web for UI creation.Detailed data source information including file details.
Raw data source information, varies by
data_source_type.How the document was created.
upload_file for file uploads, notion_import for Notion imports.ID of the processing rule applied to this document.
Timestamp when the document was disabled.
null if enabled.ID of the user who disabled the document.
null if enabled.User-facing display status derived from
indexing_status and enabled state.Document chunking mode.
text_model for standard text chunking, hierarchical_model for parent-child structure, qa_model for QA pair extraction.Metadata values assigned to this document.
Whether the document is enabled for retrieval.
Error message if indexing failed.
null when no error.Number of times the document has been matched in retrieval queries.
Unique identifier of the document.
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.Document name.
Whether a summary needs to be generated for this document.
Display position of the document in the list.
Status of the summary index for this document.
null if summary indexing is not configured.Total number of tokens in the document.
Total word count of the document.
Whether more items exist on the next page.
Number of items per page.
Current page number.
Total number of matching items.