> ## Documentation Index
> Fetch the complete documentation index at: https://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](/en/cloud/use-dify/knowledge/readme) 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.

<Note>
  A single Knowledge Base API key has access to every knowledge base visible to the account that created the key. Handle your keys carefully to avoid unintended data exposure.
</Note>

## 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.
</Warning>

## Manage API Access for a Knowledge Base

Every knowledge base is reachable through the API by default. To restrict a specific knowledge base, open it, click **API Access** in the bottom-left corner, and turn the toggle off.

## Create and Manage Knowledge Bases

* **[Create an Empty Knowledge Base](/en/api-reference/knowledge-bases/create-an-empty-knowledge-base)**: create a knowledge base with no documents yet.
* **[List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases)**: a paginated list, filterable by keyword or tag.
* **[Get Knowledge Base](/en/api-reference/knowledge-bases/get-knowledge-base)**: one knowledge base's embedding model, retrieval configuration, and document statistics.
* **[Update Knowledge Base](/en/api-reference/knowledge-bases/update-knowledge-base)**: change the name, permissions, embedding model, or retrieval settings; only the fields you provide are updated.
* **[Delete Knowledge Base](/en/api-reference/knowledge-bases/delete-knowledge-base)**: permanently remove a knowledge base and every document inside it.
* **[Retrieve Chunks from a Knowledge Base / Test Retrieval](/en/api-reference/knowledge-bases/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:

<Steps>
  <Step title="Create a knowledge base">
    Call [Create an Empty Knowledge Base](/en/api-reference/knowledge-bases/create-an-empty-knowledge-base), or use an existing knowledge base.
  </Step>

  <Step title="Add a document">
    Call [Create Document by Text](/en/api-reference/documents/create-document-by-text) or [Create Document by File](/en/api-reference/documents/create-document-by-file); 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.
  </Step>

  <Step title="Poll the indexing status">
    Poll [Get Document Indexing Status](/en/api-reference/documents/get-document-indexing-status) with the `batch` ID until `indexing_status` reaches `completed` or `error`; it progresses through `waiting`, `parsing`, `cleaning`, `splitting`, and `indexing` along the way.
  </Step>
</Steps>

* **[List Documents](/en/api-reference/documents/list-documents)**: a paginated list, filterable by keyword or indexing status.
* **[Get Document](/en/api-reference/documents/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](/en/api-reference/documents/download-document)**: a signed URL for the document's original uploaded file.
* **[Download Documents as ZIP](/en/api-reference/documents/download-documents-as-zip)**: bundle up to 100 uploaded-file documents into a single archive.
* **[Update Document](/en/api-reference/documents/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](/en/api-reference/documents/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](/en/api-reference/documents/update-document-by-file)**: deprecated alias for uploading a replacement file; use Update Document instead.
* **[Update Document Status in Batch](/en/api-reference/documents/update-document-status-in-batch)**: enable, disable, archive, or unarchive multiple documents at once.
* **[Delete Document](/en/api-reference/documents/delete-document)**: permanently remove a document and every chunk inside it.

## Manage Chunks and Child Chunks

* **[Create Chunks](/en/api-reference/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](/en/api-reference/chunks/list-chunks)**: a paginated list, filterable by keyword or status.
* **[Get Chunk](/en/api-reference/chunks/get-chunk)**: one chunk's content, keywords, and indexing status.
* **[Update Chunk](/en/api-reference/chunks/update-chunk)**: change a chunk's content, keywords, or answer; re-triggers indexing for that chunk.
* **[Delete Chunk](/en/api-reference/chunks/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](/en/api-reference/chunks/create-child-chunk)**: add a child chunk under a parent chunk.
* **[List Child Chunks](/en/api-reference/chunks/list-child-chunks)**: a paginated list of one parent chunk's child chunks.
* **[Update Child Chunk](/en/api-reference/chunks/update-child-chunk)**: change a child chunk's content.
* **[Delete Child Chunk](/en/api-reference/chunks/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](/en/api-reference/metadata/create-metadata-field)**: add a custom field to the knowledge base, typed `string`, `number`, or `time`.
* **[List Metadata Fields](/en/api-reference/metadata/list-metadata-fields)**: every field, custom and built-in, with a count of documents using each.
* **[Update Metadata Field](/en/api-reference/metadata/update-metadata-field)**: rename a custom field.
* **[Delete Metadata Field](/en/api-reference/metadata/delete-metadata-field)**: remove a custom field; documents lose their values for it.
* **[Get Built-in Metadata Fields](/en/api-reference/metadata/get-built-in-metadata-fields)**: the system-provided fields, such as `document_name`, `uploader`, and `upload_date`.
* **[Update Built-in Metadata Field](/en/api-reference/metadata/update-built-in-metadata-field)**: enable or disable built-in fields for the knowledge base.
* **[Update Document Metadata in Batch](/en/api-reference/metadata/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](/en/api-reference/tags/create-knowledge-tag)**: create a tag for organizing knowledge bases.
* **[List Knowledge Tags](/en/api-reference/tags/list-knowledge-tags)**: every tag in the workspace.
* **[Update Knowledge Tag](/en/api-reference/tags/update-knowledge-tag)**: rename a tag.
* **[Delete Knowledge Tag](/en/api-reference/tags/delete-knowledge-tag)**: remove a tag from every knowledge base it was bound to, without deleting those knowledge bases.
* **[Create Tag Binding](/en/api-reference/tags/create-tag-binding)**: bind one or more tags to a knowledge base; a knowledge base can carry multiple tags.
* **[Delete Tag Binding](/en/api-reference/tags/delete-tag-binding)**: remove tags from a knowledge base.
* **[Get Knowledge Base Tags](/en/api-reference/tags/get-knowledge-base-tags)**: the tags currently bound to one knowledge base.

## Look Up Available Models

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