> ## Documentation index > Fetch the complete documentation index at: https://dify-docs.docs7.io/llms.txt > Ask it with GET https://dify-docs.docs7.io/ask?q=. Short keywords rank best. > Use these 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. ## 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. Only the workspace owner and admins can create keys, and each workspace can have up to 10. Store your API key securely on the server side. Never expose it in client-side code or public repositories. ### Scoped API 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](/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, every document inside it, and any API key scoped only to 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: Call [Create an Empty Knowledge Base](/en/api-reference/knowledge-bases/create-an-empty-knowledge-base), or use an existing knowledge base. 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. 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. - **[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.