Knowledge Bases

Knowledge Bases resource for semantic document search operations.

AsyncKnowledgeBaseDocuments

Asynchronous document operations for a knowledge base.

Arguments:

client: The parent async client instance. knowledge_base_id: The knowledge base ID.

Methods:

create

def create(self, document_id: str, content: dict[str, Any], metadata: dict[str, Any] | None = None, generate_embedding: bool = True) -> KnowledgeBaseDocument

Add a document to the knowledge base.

Arguments:

document_id: Your own unique ID for the document (letters, numbers, - and _; up to 100 characters). Required by the API; it is the ID that get(), update() and delete() take. content: Document content matching the knowledge base schema. metadata: Optional additional metadata. generate_embedding: Whether to automatically generate embedding. Defaults to True.

Returns:

The created document.

delete

def delete(self, document_id: str) -> None

Delete a document from the knowledge base.

Arguments:

document_id: The document's documentId (the ID given on create, not id) to delete.

get

def get(self, document_id: str) -> KnowledgeBaseDocument

Get a specific document by ID.

Arguments:

document_id: The document's documentId (the ID given on create, not id).

Returns:

The document details.

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None, document_id: str | None = None) -> AsyncPage[KnowledgeBaseDocument]

List documents in the knowledge base.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. search: Search term to filter documents. document_id: Only return documents whose documentId contains this value (case-insensitive). Use get() for an exact match.

Returns:

An AsyncPage of documents with pagination support.

update

def update(self, document_id: str, content: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None, regenerate_embedding: bool = False) -> KnowledgeBaseDocument

Update a document in the knowledge base.

Arguments:

document_id: The document's documentId (the ID given on create, not id) to update. content: Updated document content. metadata: Updated metadata. regenerate_embedding: Whether to force embedding regeneration. Defaults to False.

Returns:

The updated document.

AsyncKnowledgeBases

Asynchronous knowledge base operations.

Example:

>>> async with AsyncClient(api_key="...") as client:
    ...     async for kb in (await client.knowledge_bases.list()).auto_paging_iter_async():
    ...         print(f"{kb.name}: {kb.documentCount} documents")

Arguments:

client: The parent async client instance.

Methods:

create

def create(self, name: str, description: str, schema: dict[str, Any], indexing_preferences: dict[str, Any] | None = None) -> KnowledgeBase

Create a new knowledge base.

Arguments:

name: Unique name for the knowledge base. description: Description of the knowledge base. schema: JSON schema for documents in this knowledge base. indexing_preferences: Optional indexing configuration.

Returns:

The created knowledge base.

delete

def delete(self, knowledge_base_id: str) -> None

Delete a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to delete.

documents

def documents(self, knowledge_base_id: str) -> AsyncKnowledgeBaseDocuments

Access document operations for a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID.

Returns:

An AsyncKnowledgeBaseDocuments instance for document operations.

get

def get(self, knowledge_base_id: str) -> KnowledgeBase

Get a specific knowledge base by ID.

Arguments:

knowledge_base_id: The knowledge base ID.

Returns:

The knowledge base details.

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None, is_active: bool | None = None) -> AsyncPage[KnowledgeBase]

List knowledge bases.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. search: Search term to filter by name or description. is_active: Filter by active status.

Returns:

An AsyncPage of knowledge bases with pagination support.

search

def search(self, knowledge_base_id: str, query: str, limit: int | None = None, similarity_threshold: float | None = None, include_metadata: bool | None = None) -> SearchResult

Perform semantic search in a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to search. query: Search query text. limit: Maximum number of results (1-50). similarity_threshold: Minimum similarity score (0-1). include_metadata: Include document metadata in results.

Returns:

Search results with similarity scores.

sync

def sync(self, knowledge_base_id: str, regenerate_embeddings: bool | None = None, force: bool | None = None, max_retries: int = 0) -> SyncResult

Trigger manual synchronization of a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to sync. regenerate_embeddings: Whether to regenerate existing embeddings. force: Force regeneration of all embeddings. The server defaults to False. max_retries: Retries for this request. Defaults to 0: a timed-out sync may still be running on the server, and each retry starts the whole sync again (and is billed). For large knowledge bases, create the client with a larger timeout instead of retrying.

Returns:

The sync operation result.

update

def update(self, knowledge_base_id: str, name: str | None = None, description: str | None = None, schema: dict[str, Any] | None = None, indexing_preferences: dict[str, Any] | None = None, is_active: bool | None = None) -> KnowledgeBase

Update a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to update. name: New name for the knowledge base. description: New description. schema: Updated JSON Schema for the knowledge base's documents. indexing_preferences: Updated indexing preferences. is_active: Active status.

Returns:

The updated knowledge base.

Properties:

• with_raw_response : Access methods that return raw HTTP responses.

KnowledgeBaseDocuments

Synchronous document operations for a knowledge base.

Arguments:

client: The parent client instance. knowledge_base_id: The knowledge base ID.

Methods:

create

def create(self, document_id: str, content: dict[str, Any], metadata: dict[str, Any] | None = None, generate_embedding: bool = True) -> KnowledgeBaseDocument

Add a document to the knowledge base.

Arguments:

document_id: Your own unique ID for the document (letters, numbers, - and _; up to 100 characters). Required by the API; it is the ID that get(), update() and delete() take. content: Document content matching the knowledge base schema. metadata: Optional additional metadata. generate_embedding: Whether to automatically generate embedding. Defaults to True.

Returns:

The created document.

Example:

>>> doc = client.knowledge_bases.documents("kb_123").create(
    ...     document_id="user-guide",
    ...     content={"title": "User Guide", "text": "..."},
    ...     metadata={"source": "manual"}
    ... )
    >>> print(f"Created: {doc.id}")

delete

def delete(self, document_id: str) -> None

Delete a document from the knowledge base.

Arguments:

document_id: The document's documentId (the ID given on create, not id) to delete.

Raises:

NotFoundError: If the document doesn't exist.

Example:

>>> client.knowledge_bases.documents("kb_123").delete("doc_456")

get

def get(self, document_id: str) -> KnowledgeBaseDocument

Get a specific document by ID.

Arguments:

document_id: The document's documentId (the ID given on create, not id).

Returns:

The document details.

Raises:

NotFoundError: If the document doesn't exist.

Example:

>>> doc = client.knowledge_bases.documents("kb_123").get("doc_456")
    >>> print(doc.content)

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None, document_id: str | None = None) -> Page[KnowledgeBaseDocument]

List documents in the knowledge base.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. search: Search term to filter documents. document_id: Only return documents whose documentId contains this value (case-insensitive). Use get() for an exact match.

Returns:

A Page of documents with pagination support.

Example:

>>> docs = client.knowledge_bases.documents("kb_123").list()
    >>> for doc in docs.auto_paging_iter():
    ...     print(doc.id)

update

def update(self, document_id: str, content: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None, regenerate_embedding: bool = False) -> KnowledgeBaseDocument

Update a document in the knowledge base.

Arguments:

document_id: The document's documentId (the ID given on create, not id) to update. content: Updated document content. metadata: Updated metadata. regenerate_embedding: Whether to force embedding regeneration. Defaults to False.

Returns:

The updated document.

Example:

>>> doc = client.knowledge_bases.documents("kb_123").update(
    ...     "doc_456",
    ...     content={"title": "Updated Guide", "text": "..."}
    ... )

KnowledgeBases

Synchronous knowledge base operations.

Example:

>>> client = Client(api_key="...")
    >>> # List knowledge bases
    >>> for kb in client.knowledge_bases.list().auto_paging_iter():
    ...     print(f"{kb.name}: {kb.documentCount} documents")
    >>>
    >>> # Search in a knowledge base
    >>> results = client.knowledge_bases.search("kb_123", query="authentication")
    >>> for item in results.data:
    ...     print(f"{item.document.id}: {item.similarity:.2%}")

Arguments:

client: The parent client instance.

Methods:

create

def create(self, name: str, description: str, schema: dict[str, Any], indexing_preferences: dict[str, Any] | None = None) -> KnowledgeBase

Create a new knowledge base.

Arguments:

name: Unique name for the knowledge base. description: Description of the knowledge base. schema: JSON schema for documents in this knowledge base. indexing_preferences: Optional indexing configuration.

Returns:

The created knowledge base.

Raises:

ConflictError: If a knowledge base with that name already exists.

Example:

>>> kb = client.knowledge_bases.create(
    ...     name="User Documentation",
    ...     description="Product user guides and manuals",
    ...     schema={"type": "object", "properties": {"title": {"type": "string"}}}
    ... )
    >>> print(f"Created: {kb.id}")

delete

def delete(self, knowledge_base_id: str) -> None

Delete a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to delete.

Raises:

NotFoundError: If the knowledge base doesn't exist.

Example:

>>> client.knowledge_bases.delete("kb_123")

documents

def documents(self, knowledge_base_id: str) -> KnowledgeBaseDocuments

Access document operations for a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID.

Returns:

A KnowledgeBaseDocuments instance for document operations.

Example:

>>> docs = client.knowledge_bases.documents("kb_123")
    >>> for doc in docs.list().auto_paging_iter():
    ...     print(doc.content)

get

def get(self, knowledge_base_id: str) -> KnowledgeBase

Get a specific knowledge base by ID.

Arguments:

knowledge_base_id: The knowledge base ID.

Returns:

The knowledge base details.

Raises:

NotFoundError: If the knowledge base doesn't exist.

Example:

>>> kb = client.knowledge_bases.get("kb_123")
    >>> print(f"{kb.name}: {kb.description}")

list

def list(self, page: int | None = None, limit: int | None = None, search: str | None = None, is_active: bool | None = None) -> Page[KnowledgeBase]

List knowledge bases.

Arguments:

page: Page number (1-indexed). Defaults to 1. limit: Number of items per page. search: Search term to filter by name or description. is_active: Filter by active status.

Returns:

A Page of knowledge bases with pagination support.

Example:

>>> for kb in client.knowledge_bases.list().auto_paging_iter():
    ...     print(f"{kb.name}: {kb.documentCount} documents")

search

def search(self, knowledge_base_id: str, query: str, limit: int | None = None, similarity_threshold: float | None = None, include_metadata: bool | None = None) -> SearchResult

Perform semantic search in a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to search. query: Search query text. limit: Maximum number of results (1-50). similarity_threshold: Minimum similarity score (0-1). include_metadata: Include document metadata in results.

Returns:

Search results with similarity scores.

Example:

>>> results = client.knowledge_bases.search(
    ...     "kb_123",
    ...     query="how to configure authentication",
    ...     limit=5
    ... )
    >>> for item in results.data:
    ...     print(f"{item.similarity:.2%}: {item.document.content}")

sync

def sync(self, knowledge_base_id: str, regenerate_embeddings: bool | None = None, force: bool | None = None, max_retries: int = 0) -> SyncResult

Trigger manual synchronization of a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to sync. regenerate_embeddings: Whether to regenerate existing embeddings. force: Force regeneration of all embeddings. The server defaults to False. max_retries: Retries for this request. Defaults to 0: a timed-out sync may still be running on the server, and each retry starts the whole sync again (and is billed). For large knowledge bases, create the client with a larger timeout instead of retrying.

Returns:

The sync operation result.

Example:

>>> result = client.knowledge_bases.sync("kb_123", regenerate_embeddings=True)
    >>> print(f"Sync status: {result.status}")

update

def update(self, knowledge_base_id: str, name: str | None = None, description: str | None = None, schema: dict[str, Any] | None = None, indexing_preferences: dict[str, Any] | None = None, is_active: bool | None = None) -> KnowledgeBase

Update a knowledge base.

Arguments:

knowledge_base_id: The knowledge base ID to update. name: New name for the knowledge base. description: New description. schema: Updated JSON Schema for the knowledge base's documents. indexing_preferences: Updated indexing preferences. is_active: Active status.

Returns:

The updated knowledge base.

Example:

>>> kb = client.knowledge_bases.update(
    ...     "kb_123",
    ...     description="Updated documentation"
    ... )

Properties:

• with_raw_response : Access methods that return raw HTTP responses.