Knowledge Bases

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

import DocuTray from 'docutray';

const client = new DocuTray({ apiKey: 'YOUR_API_KEY' });

for await (const kb of client.knowledgeBases.list().autoPagingIter()) {
  console.log(`${kb.name}: ${kb.documentCount} documents`);
}

curl https://app.docutray.com/api/knowledge-bases \
  -H "Authorization: Bearer YOUR_API_KEY"

# With filters
curl "https://app.docutray.com/api/knowledge-bases?isActive=true&search=docs&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

console.log(`Name: ${kb.name}`);
console.log(`Description: ${kb.description}`);
console.log(`Documents: ${kb.documentCount}`);
console.log(`Active: ${kb.isActive}`);

curl https://app.docutray.com/api/knowledge-bases/kb_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

console.log(`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')}")

const results = await client.knowledgeBases.search('kb_abc123', {
  query: 'how to configure authentication',
  limit: 5,
});

console.log(`Found ${results.resultsCount} results`);

for (const item of results.data) {
  console.log(`  [${(item.similarity * 100).toFixed(0)}%] ${item.document.content.title}`);
}

curl -X POST https://app.docutray.com/api/knowledge-bases/kb_abc123/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to configure authentication",
    "limit": 5
  }'

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

const doc = await client.knowledgeBases.documents('kb_abc123').create({
  content: {
    title: 'Getting Started Guide',
    content: 'Welcome to our product. This guide covers...',
  },
  metadata: { source: 'manual', version: '2.0' },
});

console.log(`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')}")

const docs = await client.knowledgeBases.documents('kb_abc123').list();

for (const doc of docs.data) {
  console.log(`  ${doc.id}: ${doc.content.title}`);
}

Update a Document

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

const doc = await client.knowledgeBases.documents('kb_abc123').update('doc_xyz', {
  content: { title: 'Updated Guide', content: 'New content...' },
});

Delete a Document

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

await client.knowledgeBases.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}")

const result = await client.knowledgeBases.sync('kb_abc123');

console.log(`Status: ${result.status}`);
console.log(`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()

import DocuTray, { DocuTrayError } from 'docutray';

const client = new DocuTray({ apiKey: 'YOUR_API_KEY' });

try {
  // Create a knowledge base
  const kb = await client.knowledgeBases.create({
    name: 'FAQ Database',
    description: 'Frequently asked questions and answers',
  });
  console.log(`Created KB: ${kb.id}`);

  // Add documents
  const docs = client.knowledgeBases.documents(kb.id);

  await docs.create({
    content: {
      question: 'How do I reset my password?',
      answer: 'Go to Settings > Security > Change Password',
    },
  });

  await docs.create({
    content: {
      question: 'What file formats are supported?',
      answer: 'JPEG, PNG, GIF, BMP, WebP, and PDF up to 100MB',
    },
  });

  // Search the knowledge base
  const results = await client.knowledgeBases.search(kb.id, {
    query: 'how to change my password',
    limit: 3,
  });

  console.log(`\nSearch results (${results.resultsCount} found):`);
  for (const item of results.data) {
    const content = item.document.content;
    console.log(`  [${(item.similarity * 100).toFixed(0)}%] ${content.question}`);
    console.log(`    → ${content.answer}`);
  }
} catch (error) {
  if (error instanceof DocuTrayError) {
    console.error(`Error: ${error.message}`);
  }
}

SDK Reference

For detailed class and method documentation:

Knowledge Bases

On this page