List Knowledge Bases
Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.
1 min read
get/datasets
Request example
curl --request GET \
--url https://api.dify.ai/v1/datasets \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/datasets"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/datasets', {
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',
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"
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"))
.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')
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": [
{
"app_count": 0,
"author_name": "admin",
"built_in_field_enabled": true,
"chunk_structure": null,
"created_at": 1741267200,
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"data_source_type": null,
"description": "Technical documentation for the product API",
"doc_form": "text_model",
"doc_metadata": [],
"document_count": 0,
"embedding_available": true,
"embedding_model": "text-embedding-3-small",
"embedding_model_provider": "langgenius/openai/openai",
"enable_api": true,
"external_knowledge_info": null,
"external_retrieval_model": null,
"icon_info": null,
"id": "c42e2a6e-40b3-4330-96f8-f1e4d768e8c9",
"indexing_technique": "high_quality",
"is_multimodal": false,
"is_published": false,
"maintainer": "admin",
"name": "Product Documentation",
"permission": "only_me",
"pipeline_id": null,
"provider": "vendor",
"retrieval_model_dict": {
"reranking_enable": false,
"reranking_mode": null,
"reranking_model": {
"reranking_model_name": "",
"reranking_provider_name": ""
},
"score_threshold": null,
"score_threshold_enabled": false,
"search_method": "semantic_search",
"top_k": 3,
"weights": null
},
"runtime_mode": null,
"summary_index_setting": null,
"tags": [],
"total_available_documents": 0,
"total_documents": 0,
"updated_at": 1741267200,
"updated_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"word_count": 0
}
],
"has_more": false,
"limit": 20,
"page": 1,
"total": 1
}{
"code": "forbidden",
"message": "The API key is not authorized to access this knowledge base.",
"status": 403
}get/datasets
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).
Query parameters
Search keyword to filter by name.
Tag IDs to filter by. Get tag IDs from List Knowledge Type Tags.
Responses
application/json
List of knowledge bases.
Array of knowledge base objects.
Show child attributesHide child attributes
Number of applications currently using this knowledge base.
Display name of the creator.
Whether built-in metadata fields (e.g.,
document_name, uploader) are enabled.Chunk structure configuration.
Creation timestamp (Unix epoch in seconds).
ID of the user who created the knowledge base.
Data source type of the documents,
null if not yet configured.Optional text describing the purpose or contents of the knowledge base.
Document chunking mode.
text_model for standard text chunking, hierarchical_model for parent-child structure, qa_model for QA pair extraction.Metadata field definitions for the knowledge base.
Total number of documents in the knowledge base.
Whether the configured embedding model is currently available.
Name of the embedding model used for indexing.
Embedding model provider identifier, formatted as
organization/plugin_name/provider_name (e.g. langgenius/openai/openai). Legacy knowledge bases may return the bare short form (e.g. openai).Whether API access is enabled for this knowledge base.
Connection details for external knowledge bases. Present when
provider is external.Show child attributesHide child attributes
Retrieval settings for external knowledge bases.
null for internal knowledge bases.Icon display configuration for the knowledge base.
Unique identifier of the knowledge base.
high_quality uses embedding models for precise search; economy uses keyword-based indexing.Whether multimodal content processing is enabled.
Whether the knowledge base is published.
Display name of the knowledge base maintainer.
null if not set.Display name of the knowledge base. Unique within the workspace.
Account IDs of members granted access when
permission is partial_members. Always present on the update response; on the detail response, present only when permission is partial_members.Controls who can access this knowledge base. Possible values:
only_me, all_team_members, partial_members.Pipeline ID, if a custom processing pipeline is configured.
Provider type.
vendor for internally managed, external for external knowledge base connections.Retrieval configuration for the knowledge base.
Show child attributesHide child attributes
Whether reranking is enabled.
Reranking mode.
reranking_model for model-based reranking, weighted_score for score-based weighting. null if reranking is disabled.Reranking model configuration.
Show child attributesHide child attributes
Minimum similarity score for results. Only effective when
score_threshold_enabled is true.Whether score threshold filtering is enabled.
Search method used for retrieval.
keyword_search for keyword matching, semantic_search for embedding-based similarity, full_text_search for full-text indexing, hybrid_search for a combination of semantic and keyword approaches.Maximum number of results to return.
Weight configuration for hybrid search.
Show child attributesHide child attributes
Keyword search weight settings.
Show child attributesHide child attributes
Weight assigned to keyword search results.
Semantic search weight settings.
Strategy for balancing semantic and keyword search weights.
Runtime processing mode.
Summary index configuration.
Tags associated with this knowledge base.
Number of documents that are enabled and available.
Total number of documents.
Last update timestamp (Unix epoch in seconds).
ID of the user who last updated the knowledge base.
Total word count across all documents.
Whether more items exist on the next page.
Number of items per page.
Current page number.
Total number of matching items.