Knowledge API

Build and maintain knowledge bases from your own code, without going through the Dify console: create a knowledge base, load documents and chunks into it, organize them with metadata and tags, and query it directly for search or RAG.

​

Get Your API Endpoint and Key

In Knowledge, click Service API in the top-right corner to open the API configuration panel. From here:

• Copy the Service API endpoint, the base URL for every Knowledge API request.
• Click API Key to create and manage keys.

​

Scoped API Keys

When you create a key, scope it to specific knowledge bases the integration needs to work with. Choose all knowledge bases if the integration needs to list or create knowledge bases. A scoped key can call only endpoints whose path includes a dataset_id in its scope. Calls with another ID, or without a dataset_id in the path, return 403 forbidden. For a scoped key, open the knowledge base in Dify and copy the ID after /datasets/ in the page URL. Use that value as the dataset_id in the request path. To change the scope, create a replacement key. Switch your integration to the new key before deleting the old one. Deleting a knowledge base also deletes any key scoped only to it. A key that also covers other knowledge bases keeps working for those.

​

Manage API Access for a Knowledge Base

API access is on for every knowledge base by default. To close one knowledge base to every key, open it, and disable API Access in the lower-left corner.

​

Create and Manage Knowledge Bases

• Create an Empty Knowledge Base: create a knowledge base with no documents yet.
• List Knowledge Bases: a paginated list, filterable by keyword or tag.
• Get Knowledge Base: one knowledge base’s embedding model, retrieval configuration, and document statistics.
• Update Knowledge Base: change the name, permissions, embedding model, or retrieval settings; only the fields you provide are updated.
• Delete Knowledge Base: permanently remove a knowledge base, every document inside it, and any API key scoped only to it.
• Retrieve Chunks from a Knowledge Base / Test Retrieval: search a knowledge base and return the most relevant chunks—the same endpoint serves production retrieval and retrieval testing.

​

Add and Update Documents

Document creation is asynchronous. Create the document, then poll until indexing finishes:

• List Documents: a paginated list, filterable by keyword or indexing status.
• Get Document: one document’s indexing status, metadata, and processing statistics; the metadata query parameter includes, omits, or returns only the metadata fields.
• Download Document: a signed URL for the document’s original uploaded file.
• Download Documents as ZIP: bundle up to 100 uploaded-file documents into a single archive.
• Update Document: replace a document’s content by uploading a new file, re-triggering indexing; the canonical way to update a file-based document.
• Update Document by Text: update a document’s text content, name, or processing configuration inline; re-triggers indexing when the content changes.
• Update Document by File: deprecated alias for uploading a replacement file; use Update Document instead.
• Update Document Status in Batch: enable, disable, archive, or unarchive multiple documents at once.
• Delete Document: permanently remove a document and every chunk inside it.

​

Manage Chunks and Child Chunks

• Create Chunks: add chunks to a document by hand—indexing already chunks uploaded content automatically. Each chunk requires content; documents in Q&A mode also require answer.
• List Chunks: a paginated list, filterable by keyword or status.
• Get Chunk: one chunk’s content, keywords, and indexing status.
• Update Chunk: change a chunk’s content, keywords, or answer; re-triggers indexing for that chunk.
• Delete Chunk: permanently remove a chunk.

For documents in Parent-child mode (hierarchical_model), child chunks nest under a parent chunk. Child chunks you create or update through the API are always typed customized, unlike the automatic ones the indexing pipeline generates.

• Create Child Chunk: add a child chunk under a parent chunk.
• List Child Chunks: a paginated list of one parent chunk’s child chunks.
• Update Child Chunk: change a child chunk’s content.
• Delete Child Chunk: permanently remove a child chunk.

​

Manage Metadata Fields

Metadata fields annotate documents with structured information that retrieval can filter on:

• Create Metadata Field: add a custom field to the knowledge base, typed string, number, or time.
• List Metadata Fields: every field, custom and built-in, with a count of documents using each.
• Update Metadata Field: rename a custom field.
• Delete Metadata Field: remove a custom field; documents lose their values for it.
• Get Built-in Metadata Fields: the system-provided fields, such as document_name, uploader, and upload_date.
• Update Built-in Metadata Field: enable or disable built-in fields for the knowledge base.
• Update Document Metadata in Batch: set metadata key-value pairs across multiple documents in a single call.

Metadata also works as a stable external key: store your source system’s ID on each document, then filter on it in later sync runs to find and update the same documents.

​

Organize Knowledge Bases with Tags

Tags live at the workspace level, independent of any single knowledge base:

• Create Knowledge Tag: create a tag for organizing knowledge bases.
• List Knowledge Tags: every tag in the workspace.
• Update Knowledge Tag: rename a tag.
• Delete Knowledge Tag: remove a tag from every knowledge base it was bound to, without deleting those knowledge bases.
• Create Tag Binding: bind one or more tags to a knowledge base; a knowledge base can carry multiple tags.
• Delete Tag Binding: remove tags from a knowledge base.
• Get Knowledge Base Tags: the tags currently bound to one knowledge base.

​

Look Up Available Models

• Get Available Models: the models available for a given model_type; query text-embedding for embedding models or rerank for reranking models when configuring a knowledge base.

​

Run the Knowledge Pipeline

A knowledge pipeline is a workflow that ingests data from a datasource and turns it into documents:

• Upload Pipeline File: upload a file for the pipeline to process.
• List Datasource Plugins: the datasource nodes configured in the pipeline—published by default, or the draft version with is_published=false.
• Run Datasource Node: execute a single datasource node and stream its results, useful for testing one step in isolation.
• Run Pipeline: execute the full pipeline in streaming or blocking response mode; is_published picks the published version or the current draft.