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.
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.
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: 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 and every document inside 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:Create a knowledge base
Call Create an Empty Knowledge Base, or use an existing knowledge base.
Add a document
Call Create Document by Text or 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 the indexing status
Poll 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: a paginated list, filterable by keyword or indexing status.
- Get Document: one document’s indexing status, metadata, and processing statistics; the
metadataquery 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 requireanswer. - 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.
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, ortime. - 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, andupload_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.
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; querytext-embeddingfor embedding models orrerankfor 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
streamingorblockingresponse mode;is_publishedpicks the published version or the current draft.