DocuTray
DocumentationAPI ReferenceDocuTray.com
Python SDKResources

Knowledge Bases

Python SDK - Knowledge Bases resource API reference

Knowledge Bases resource for semantic document search operations.

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, content: dict[str, Any], document_id: str | None = None, metadata: dict[str, Any] | None = None, generate_embedding: bool = True) -> KnowledgeBaseDocument

Add a document to the knowledge base.

Arguments:

  • content: Document content matching the knowledge base schema.
  • document_id: Optional external document reference ID.
  • 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(
    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 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 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) -> 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.

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 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")
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) -> SyncResult

Trigger manual synchronization of a knowledge base.

Arguments:

  • knowledge_base_id: The knowledge base ID to sync.
  • regenerate_embeddings: Whether to regenerate all embeddings.

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, 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.
  • 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.

AsyncKnowledgeBaseDocuments

Asynchronous document operations for a knowledge base.

Arguments:

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

Methods:

create

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

Add a document to the knowledge base.

Arguments:

  • content: Document content matching the knowledge base schema.
  • document_id: Optional external document reference ID.
  • metadata: Optional additional metadata.
  • generate_embedding: Whether to automatically generate embedding. Defaults to True.

Returns:

The created document.

delete

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

Delete a document from the knowledge base.

Arguments:

  • document_id: The document ID to delete.

get

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

Get a specific document by ID.

Arguments:

  • document_id: The document ID.

Returns:

The document details.

list

async def list(self, page: int | None = None, limit: int | None = None, search: 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.

Returns:

An AsyncPage of documents with pagination support.

update

async 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 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

async 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

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

Delete a knowledge base.

Arguments:

  • knowledge_base_id: The knowledge base ID to delete.

documents

async 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

async 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

async 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

async 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

async def sync(self, knowledge_base_id: str, regenerate_embeddings: bool | None = None) -> SyncResult

Trigger manual synchronization of a knowledge base.

Arguments:

  • knowledge_base_id: The knowledge base ID to sync.
  • regenerate_embeddings: Whether to regenerate all embeddings.

Returns:

The sync operation result.

update

async def update(self, knowledge_base_id: str, name: str | None = None, description: str | 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.
  • is_active: Active status.

Returns:

The updated knowledge base.

Properties:

  • with_raw_response: Access methods that return raw HTTP responses.

Steps

Python SDK - Steps resource API reference

Convert Types

Python SDK - Convert type definitions

On this page

KnowledgeBaseDocumentscreatedeletegetlistupdateKnowledgeBasescreatedeletedocumentsgetlistsearchsyncupdateAsyncKnowledgeBaseDocumentscreatedeletegetlistupdateAsyncKnowledgeBasescreatedeletedocumentsgetlistsearchsyncupdate