A single Knowledge Base API key has access to every knowledge base visible to the workspace owner — dataset API requests execute with owner-level access, regardless of who created the key. Handle your keys carefully to avoid unintended data exposure.
Get Your API Endpoint and Key
In Knowledge, open the API Access tab. From here:- Copy the API Server address, the base URL for every Knowledge API request.
- Click API Key to create and manage keys.
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:1
Create a knowledge base
Call Create an Empty Knowledge Base, or use an existing knowledge base.
2
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.3
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.
- 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: replace a document’s content by uploading a new file, re-triggering indexing.
- 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.