agents-store Dify — Knowledge Base / Datasets API
A separate API from the app Service API, for managing knowledge bases (datasets), documents, and chunks (segments). Used by RAG-enabled apps. Authentication is the same Bearer pattern, but with a Knowledge API key (Dify → Knowledge → API), not an app key.
Base URL is the same as the Service API (https://api.dify.ai/v1 or self-hosted
https://{host}/v1). For auth fundamentals see the setup skill.
"Dataset" and "knowledge base" are the same object. The
dataset_idequals theknowledge_base_idyou see in app configs.
Quick map
| Group | Endpoints | Reference |
|---|---|---|
| Datasets | create / list / get / update / delete / retrieve | references/datasets.md |
| Documents | create (text/file) / list / get / update / delete / indexing-status / batch | references/documents-segments.md |
| Segments (chunks) | list / create / get / update / delete + child chunks | references/documents-segments.md |
| Tags / Metadata / Models | dataset tags, metadata schema, embedding models | below |
Most common flow (ingest → index → retrieve)
# 1) Create a knowledge base
curl -X POST 'https://api.dify.ai/v1/datasets' \
--header 'Authorization: Bearer dataset-XXXX' \
--header 'Content-Type: application/json' \
--data '{ "name": "Product Docs", "permission": "only_me" }'
# → { "id": "<dataset_id>", ... }
# 2) Add a document by text (creates an indexing batch)
curl -X POST 'https://api.dify.ai/v1/datasets/{dataset_id}/document/create-by-text' \
--header 'Authorization: Bearer dataset-XXXX' \
--header 'Content-Type: application/json' \
--data '{
"name": "FAQ",
"text": "Q: Hours? A: 9-5 weekdays.",
"indexing_technique": "high_quality",
"process_rule": { "mode": "automatic" }
}'
# → { "document": { "id": "<document_id>", ... }, "batch": "<batch>" }
# 3) Poll indexing status
curl 'https://api.dify.ai/v1/datasets/{dataset_id}/documents/{batch}/indexing-status' \
--header 'Authorization: Bearer dataset-XXXX'
# 4) Test retrieval
curl -X POST 'https://api.dify.ai/v1/datasets/{dataset_id}/retrieve' \
--header 'Authorization: Bearer dataset-XXXX' \
--header 'Content-Type: application/json' \
--data '{ "query": "What are your hours?", "retrieval_model": { "top_k": 3 } }'
See the references for every field and the full document/segment lifecycle.
Tags (knowledge type tags)
# List tags bound to a dataset
curl 'https://api.dify.ai/v1/datasets/{dataset_id}/tags' \
--header 'Authorization: Bearer dataset-XXXX'
Workspace-level tag management lives under /datasets/tags (GET list, POST create,
PATCH rename, DELETE remove) plus /datasets/tags/binding and /datasets/tags/unbinding
to attach/detach tags to a dataset.
Metadata
# List a dataset's metadata fields
curl 'https://api.dify.ai/v1/datasets/{dataset_id}/metadata' \
--header 'Authorization: Bearer dataset-XXXX'
POST /datasets/{dataset_id}/metadata creates a field; PATCH/DELETE
/datasets/{dataset_id}/metadata/{metadata_id} rename/remove; POST /datasets/{dataset_id}/documents/metadata assigns metadata values to documents;
POST /datasets/{dataset_id}/metadata/built-in/{action} toggles built-in metadata.
Embedding models
# Text-embedding models available for indexing
curl 'https://api.dify.ai/v1/workspaces/current/models/model-types/text-embedding' \
--header 'Authorization: Bearer dataset-XXXX'
Endpoint summary
| Endpoint | Method | Purpose |
|---|---|---|
/datasets |
GET / POST | List / create knowledge bases |
/datasets/{id} |
GET / PATCH / DELETE | Get / update / delete a knowledge base |
/datasets/{id}/retrieve |
POST | Test retrieval (RAG query) |
/datasets/{id}/document/create-by-text |
POST | Add a document from text |
/datasets/{id}/document/create-by-file |
POST | Add a document from a file |
/datasets/{id}/documents |
GET | List documents |
/datasets/{id}/documents/{batch}/indexing-status |
GET | Indexing progress |
/datasets/{id}/documents/{document_id} |
DELETE | Delete a document |
/datasets/{id}/documents/{document_id}/segments |
GET / POST | List / add chunks |
/datasets/{id}/documents/{document_id}/segments/{segment_id} |
POST / DELETE | Update / delete a chunk |
/datasets/{id}/tags |
GET | Tags bound to a dataset |
/datasets/{id}/metadata |
GET / POST | Metadata schema |
Full parameter tables and the rest of the document/segment endpoints are in the two reference files linked above.