Knowledge Bases

KnowledgeBases

Resource for managing knowledge bases and their documents. Access via client.knowledgeBases.

Single-resource methods (get, create, update, sync and the document get, create and update) return the knowledge base, document or sync result directly; the API's { data } envelope is unwrapped. withRawResponse returns the envelope as is (KnowledgeBaseEnvelope<T>).

Methods

list(params?, options?)

Lists knowledge bases with pagination. search matches the name or description; isActive: false lists deleted knowledge bases.

const page = await client.knowledgeBases.list({ limit: 10, search: 'catalog' });

for (const kb of page.data) {
  console.log(kb.name, kb._count?.documents);
}

Parameters: KnowledgeBaseListParams (optional) Returns: Promise<Page<KnowledgeBase>>

get(id, options?)

Retrieves a single knowledge base by ID.

const kb = await client.knowledgeBases.get('kb_abc123');

Returns: Promise<KnowledgeBase>

create(params, options?)

Creates a new knowledge base. name, description and schema are required.

const kb = await client.knowledgeBases.create({
  name: 'Product catalog',
  description: 'Product information database',
  schema: {
    type: 'object',
    properties: { sku: { type: 'string' }, title: { type: 'string' } },
  },
});

Parameters: KnowledgeBaseCreateParams

Returns: Promise<KnowledgeBase>

update(id, params, options?)

Updates an existing knowledge base. isActive: true restores a deleted one.

const kb = await client.knowledgeBases.update('kb_abc123', {
  name: 'Updated catalog',
});

Parameters: id: string, KnowledgeBaseUpdateParams

Returns: Promise<KnowledgeBase>

delete(id, options?)

Deletes a knowledge base.

await client.knowledgeBases.delete('kb_abc123');

Returns: Promise<void>

search(id, params, options?)

Searches a knowledge base for matching documents. Only documents with an embedding are searched.

const results = await client.knowledgeBases.search('kb_abc123', {
  query: 'invoice total',
  limit: 5,
  similarityThreshold: 0.8,
});

for (const item of results.data) {
  console.log(item.document.content, item.similarity);
}

Parameters: id: string, KnowledgeBaseSearchParams Returns: Promise<SearchResult>

sync(id, params?, options?)

Regenerates the embeddings of the knowledge base's documents and waits until the sync finishes, which can take minutes for a large knowledge base: pass a longer timeout in options when needed.

const result = await client.knowledgeBases.sync(
  'kb_abc123',
  { force: true },
  { timeout: 600_000 },
);
console.log(result.status, result.documentsProcessed, result.embeddingsGenerated);

Parameters: id: string, KnowledgeBaseSyncParams (optional) Returns: Promise<SyncResult>

Documents

Access knowledge base documents via client.knowledgeBases.documents(knowledgeBaseId). Documents are addressed by their documentId, the identifier you choose when creating them, not by their internal id.

documents(kbId).list(params?, options?)

Lists documents in a knowledge base. documentId filters by a partial match on it.

const docs = await client.knowledgeBases.documents('kb_abc123').list({ documentId: 'invoice-' });

Parameters: KBDocumentListParams (optional)

documents(kbId).get(documentId, options?)

Gets a single document.

const doc = await client.knowledgeBases.documents('kb_abc123').get('invoice-001');

documents(kbId).create(params, options?)

Creates a new document in the knowledge base. documentId is required and must be unique within the knowledge base. The embedding is generated right away unless generateEmbedding is false.

const doc = await client.knowledgeBases.documents('kb_abc123').create({
  documentId: 'invoice-001',
  content: { title: 'Invoice', amount: 100 },
  metadata: { source: 'upload' },
});

Parameters: KBDocumentCreateParams

documents(kbId).update(documentId, params, options?)

Updates an existing document. Changing content regenerates the embedding; regenerateEmbedding: true forces it.

const doc = await client.knowledgeBases.documents('kb_abc123').update('invoice-001', {
  content: { title: 'Updated Invoice' },
});

Parameters: documentId: string, KBDocumentUpdateParams

documents(kbId).delete(documentId, options?)

Deletes a document from the knowledge base.

await client.knowledgeBases.documents('kb_abc123').delete('invoice-001');