> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge API

> API for managing knowledge bases, documents, chunks, metadata, tags, and knowledge pipelines

Build and maintain [knowledge bases](https://enterprise-docs.dify.ai/en/3.13.x/use/knowledge/readme.md) 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.

> [!WARNING]
>
> Store your API key securely on the server side. Never expose it in client-side code or public repositories.

### 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/create-an-empty-knowledge-base.md)**: create a knowledge base with no documents yet.
* **[List Knowledge Bases](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/list-knowledge-bases.md)**: a paginated list, filterable by keyword or tag.
* **[Get Knowledge Base](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/get-knowledge-base.md)**: one knowledge base's embedding model, retrieval configuration, and document statistics.
* **[Update Knowledge Base](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/update-knowledge-base.md)**: change the name, permissions, embedding model, or retrieval settings; only the fields you provide are updated.
* **[Delete Knowledge Base](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/delete-knowledge-base.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval.md)**: 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:

**1. Create a knowledge base**

Call [Create an Empty Knowledge Base](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-bases/create-an-empty-knowledge-base.md), or use an existing knowledge base.

**2. Add a document**

Call [Create Document by Text](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/create-document-by-text.md) or [Create Document by File](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/create-document-by-file.md); both return a `batch` ID.

If you didn't set `indexing_technique` (how content is indexed for search) when creating the knowledge base, set it on this first document; later documents inherit it automatically.

**3. Poll the indexing status**

Poll [Get Document Indexing Status](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/get-document-indexing-status.md) with the `batch` ID until `indexing_status` reaches `completed` or `error`; it progresses through `waiting`, `parsing`, `cleaning`, `splitting`, and `indexing` along the way.

* **[List Documents](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/list-documents.md)**: a paginated list, filterable by keyword or indexing status.
* **[Get Document](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/get-document.md)**: one document's indexing status, metadata, and processing statistics; the `metadata` query parameter includes, omits, or returns only the metadata fields.
* **[Download Document](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/download-document.md)**: a signed URL for the document's original uploaded file.
* **[Download Documents as ZIP](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/download-documents-as-zip.md)**: bundle up to 100 uploaded-file documents into a single archive.
* **[Update Document](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/update-document.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/update-document-by-text.md)**: update a document's text content, name, or processing configuration inline; re-triggers indexing when the content changes.
* **[Update Document by File](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/update-document-by-file.md)**: deprecated alias for uploading a replacement file; use Update Document instead.
* **[Update Document Status in Batch](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/update-document-status-in-batch.md)**: enable, disable, archive, or unarchive multiple documents at once.
* **[Delete Document](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/documents/delete-document.md)**: permanently remove a document and every chunk inside it.

## Manage Chunks and Child Chunks

* **[Create Chunks](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/create-chunks.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/list-chunks.md)**: a paginated list, filterable by keyword or status.
* **[Get Chunk](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/get-chunk.md)**: one chunk's content, keywords, and indexing status.
* **[Update Chunk](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/update-chunk.md)**: change a chunk's content, keywords, or answer; re-triggers indexing for that chunk.
* **[Delete Chunk](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/delete-chunk.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/create-child-chunk.md)**: add a child chunk under a parent chunk.
* **[List Child Chunks](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/list-child-chunks.md)**: a paginated list of one parent chunk's child chunks.
* **[Update Child Chunk](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/update-child-chunk.md)**: change a child chunk's content.
* **[Delete Child Chunk](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/chunks/delete-child-chunk.md)**: permanently remove a child chunk.

## Manage Metadata Fields

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

* **[Create Metadata Field](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/create-metadata-field.md)**: add a custom field to the knowledge base, typed `string`, `number`, or `time`.
* **[List Metadata Fields](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/list-metadata-fields.md)**: every field, custom and built-in, with a count of documents using each.
* **[Update Metadata Field](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/update-metadata-field.md)**: rename a custom field.
* **[Delete Metadata Field](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/delete-metadata-field.md)**: remove a custom field; documents lose their values for it.
* **[Get Built-in Metadata Fields](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/get-built-in-metadata-fields.md)**: the system-provided fields, such as `document_name`, `uploader`, and `upload_date`.
* **[Update Built-in Metadata Field](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/update-built-in-metadata-field.md)**: enable or disable built-in fields for the knowledge base.
* **[Update Document Metadata in Batch](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/metadata/update-document-metadata-in-batch.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/create-knowledge-tag.md)**: create a tag for organizing knowledge bases.
* **[List Knowledge Tags](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/list-knowledge-tags.md)**: every tag in the workspace.
* **[Update Knowledge Tag](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/update-knowledge-tag.md)**: rename a tag.
* **[Delete Knowledge Tag](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/delete-knowledge-tag.md)**: remove a tag from every knowledge base it was bound to, without deleting those knowledge bases.
* **[Create Tag Binding](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/create-tag-binding.md)**: bind one or more tags to a knowledge base; a knowledge base can carry multiple tags.
* **[Delete Tag Binding](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/delete-tag-binding.md)**: remove tags from a knowledge base.
* **[Get Knowledge Base Tags](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/tags/get-knowledge-base-tags.md)**: the tags currently bound to one knowledge base.

## Look Up Available Models

* **[Get Available Models](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/models/get-available-models.md)**: 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](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-pipeline/upload-pipeline-file.md)**: upload a file for the pipeline to process.
* **[List Datasource Plugins](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-pipeline/list-datasource-plugins.md)**: the datasource nodes configured in the pipeline—published by default, or the draft version with `is_published=false`.
* **[Run Datasource Node](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-pipeline/run-datasource-node.md)**: execute a single datasource node and stream its results, useful for testing one step in isolation.
* **[Run Pipeline](https://enterprise-docs.dify.ai/en/3.13.x/develop/api/knowledge-pipeline/run-pipeline.md)**: execute the full pipeline in `streaming` or `blocking` response mode; `is_published` picks the published version or the current draft.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.