Knowledge Bases

Manage Docutray knowledge bases — store documents with vector embeddings for semantic search and retrieval, with multi-language SDK and REST examples.

Knowledge Bases let you store documents with embeddings for semantic search. Upload documents, and DocuTray automatically generates vector embeddings so you can search by meaning rather than exact keywords.

List Knowledge Bases

Retrieve all knowledge bases in your organization.

from docutray import Client

client = Client(api_key="YOUR_API_KEY")

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

Response

{
  "data": [
    {
      "id": "kb_abc123",
      "name": "Product Documentation",
      "description": "Technical docs and user guides",
      "isActive": true,
      "documentCount": 150,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-03-10T14:20:00.000Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

Get Knowledge Base

Retrieve details of a specific knowledge base.

kb = client.knowledge_bases.get("kb_abc123")

print(f"Name: {kb.name}")
print(f"Description: {kb.description}")
print(f"Documents: {kb.documentCount}")
print(f"Active: {kb.isActive}")

Create Knowledge Base

Create a new knowledge base with an optional JSON schema for document structure.

kb = client.knowledge_bases.create(
    name="Product Documentation",
    description="Technical docs and user guides",
    schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "content": {"type": "string"},
            "category": {"type": "string"}
        }
    }
)

print(f"Created: {kb.id}")

Semantic Search

Search a knowledge base using natural language. DocuTray converts your query to an embedding and finds the most semantically similar documents.

results = client.knowledge_bases.search(
    "kb_abc123",
    query="how to configure authentication",
    limit=5,
    similarity_threshold=0.7,
    include_metadata=True
)

print(f"Found {results.resultsCount} results")

for item in results.data:
    print(f"  [{item.similarity:.0%}] {item.document.content.get('title')}")

Search Response

{
  "data": [
    {
      "document": {
        "id": "doc_xyz",
        "content": {
          "title": "Authentication Setup Guide",
          "content": "To configure authentication..."
        },
        "metadata": { "category": "security" }
      },
      "similarity": 0.92
    }
  ],
  "query": "how to configure authentication",
  "resultsCount": 1
}

Manage Documents

Add, list, update, and remove documents from a knowledge base.

Add a Document

doc = client.knowledge_bases.documents("kb_abc123").create(
    content={
        "title": "Getting Started Guide",
        "content": "Welcome to our product. This guide covers..."
    },
    metadata={"source": "manual", "version": "2.0"},
    generate_embedding=True
)

print(f"Created document: {doc.id}")

List Documents

docs = client.knowledge_bases.documents("kb_abc123").list()

for doc in docs.auto_paging_iter():
    print(f"  {doc.id}: {doc.content.get('title')}")

Update a Document

doc = client.knowledge_bases.documents("kb_abc123").update(
    "doc_xyz",
    content={"title": "Updated Guide", "content": "New content..."},
    regenerate_embedding=False
)

Delete a Document

client.knowledge_bases.documents("kb_abc123").delete("doc_xyz")

Sync Knowledge Base

Regenerate embeddings for all documents in a knowledge base. Useful after bulk updates.

result = client.knowledge_bases.sync(
    "kb_abc123",
    regenerate_embeddings=True
)

print(f"Status: {result.status}")
print(f"Documents processed: {result.documentsProcessed}")

Parameters

List Parameters

Parameter	Type	Required	Description
`isActive`	boolean	No	Filter by active status (default: true)
`search`	string	No	Search by name or description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page, 1-100 (default: 20)

Search Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Natural language search query
`limit`	integer	No	Maximum results to return
`similarity_threshold`	float	No	Minimum similarity score (0-1)
`include_metadata`	boolean	No	Include document metadata in results

Complete Code

End-to-end example: create a knowledge base, add documents, and search.

from docutray import Client, DocuTrayError

client = Client(api_key="YOUR_API_KEY")

try:
    # Create a knowledge base
    kb = client.knowledge_bases.create(
        name="FAQ Database",
        description="Frequently asked questions and answers"
    )
    print(f"Created KB: {kb.id}")

    # Add documents
    docs_client = client.knowledge_bases.documents(kb.id)

    docs_client.create(
        content={
            "question": "How do I reset my password?",
            "answer": "Go to Settings > Security > Change Password"
        },
        generate_embedding=True
    )

    docs_client.create(
        content={
            "question": "What file formats are supported?",
            "answer": "JPEG, PNG, GIF, BMP, WebP, and PDF up to 100MB"
        },
        generate_embedding=True
    )

    # Search the knowledge base
    results = client.knowledge_bases.search(
        kb.id,
        query="how to change my password",
        limit=3
    )

    print(f"\nSearch results ({results.resultsCount} found):")
    for item in results.data:
        content = item.document.content
        print(f"  [{item.similarity:.0%}] {content.get('question')}")
        print(f"    → {content.get('answer')}")

except DocuTrayError as e:
    print(f"Error: {e.message}")
finally:
    client.close()

SDK Reference

For detailed class and method documentation:

Knowledge Bases

On this page