Knowledge Bases API

Organize documents into knowledge bases for context-aware AI chat and semantic search. See Knowledge Bases and RAG Setup for concepts and chat pipelines.

List Knowledge Bases


GET /api/knowledge-bases

Get all knowledge bases you have access to.

Response


{
  "knowledge_bases": [
    {
      "id": "kb-uuid",
      "name": "Legal Contracts",
      "description": "Collection of client contracts and agreements",
      "document_count": 45,
      "settings": {
        "retrieval": {
          "top_k": 5,
          "threshold": 0.7
        }
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Knowledge Base


POST /api/knowledge-bases

Create a new knowledge base.

Request


{
  "name": "Legal Contracts",
  "description": "Collection of client contracts and agreements",
  "settings": {
    "retrieval": {
      "top_k": 5,
      "threshold": 0.7
    }
  },
  "organization_id": "org-uuid"
}

Field	Type	Required	Description
`name`	string	Yes	Knowledge base name
`description`	string	No	Description
`settings`	object	No	Configuration settings
`organization_id`	string	No	Associate with organization

Settings Options


{
  "retrieval": {
    "top_k": 5,
    "threshold": 0.7,
    "reranking": true
  },
  "chunking": {
    "strategy": "semantic",
    "max_size": 1000,
    "overlap": 100
  }
}

Response


{
  "knowledge_base": {
    "id": "kb-uuid",
    "name": "Legal Contracts",
    "description": "Collection of client contracts and agreements",
    "settings": {...},
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Knowledge Base


GET /api/knowledge-bases/{id}

Get a specific knowledge base.

Update Knowledge Base


PATCH /api/knowledge-bases/{id}

Update knowledge base name, description, or settings.


{
  "name": "Updated Name",
  "description": "Updated description",
  "settings": {
    "retrieval": {
      "top_k": 10
    }
  }
}

Delete Knowledge Base


DELETE /api/knowledge-bases/{id}

Delete a knowledge base. Documents are not deleted, only the association.

Documents

List Documents


GET /api/knowledge-bases/{id}/documents

Get all documents in a knowledge base.

Response:


{
  "documents": [
    {
      "id": "doc-uuid",
      "name": "Service Agreement.pdf",
      "status": "completed",
      "file_type": "pdf",
      "created_at": "2024-01-10T00:00:00Z"
    }
  ]
}

Add Document


POST /api/knowledge-bases/{id}/documents

Add an existing document to the knowledge base.


{
  "document_id": "doc-uuid"
}

Batch Add Documents


POST /api/knowledge-bases/{id}/documents/batch

Add multiple documents at once (max 50).


{
  "document_ids": ["doc1", "doc2", "doc3"]
}

Response:


{
  "added": ["doc1", "doc2"],
  "failed": [
    { "id": "doc3", "error": "Document not found" }
  ]
}

Remove Document


DELETE /api/knowledge-bases/{id}/documents?document_id={doc_id}

Remove a document from the knowledge base.

Analytics


GET /api/knowledge-bases/{id}/analytics

Get analytics for a knowledge base.

Query Parameters:

Parameter	Default	Description
`days`	30	Number of days to analyze
`popular_limit`	10	Top N popular queries
`recent_limit`	10	Recent queries to show

Response:


{
  "summary": {
    "total_queries": 150,
    "avg_response_time_ms": 1200,
    "avg_confidence": 0.87,
    "feedback": {
      "positive": 120,
      "negative": 15
    }
  },
  "popular_queries": [
    {
      "query": "payment terms",
      "count": 25,
      "avg_confidence": 0.92
    }
  ],
  "recent_queries": [
    {
      "query": "liability clause",
      "timestamp": "2024-01-15T10:00:00Z",
      "confidence": 0.89
    }
  ],
  "document_usage": [
    {
      "document_id": "doc-uuid",
      "document_name": "Master Agreement.pdf",
      "citation_count": 45
    }
  ]
}

Submit Feedback


POST /api/knowledge-bases/{id}/analytics/feedback

Submit user feedback for chat quality.


{
  "message_id": "msg-uuid",
  "feedback": "thumbs_up"
}

Feedback	Description
`thumbs_up`	Positive - answer was helpful
`thumbs_down`	Negative - answer was not helpful

Templates

List Templates


GET /api/knowledge-bases/templates

Get available knowledge base templates.

Response:


{
  "templates": [
    {
      "id": "template-uuid",
      "name": "Legal Document Library",
      "description": "Pre-configured for legal documents",
      "category": "legal",
      "icon": "scale",
      "is_system_template": true,
      "settings": {...}
    }
  ]
}

Create from Template


POST /api/knowledge-bases/from-template

Create a knowledge base from a template.


{
  "template_id": "template-uuid",
  "name": "My Legal KB",
  "description": "Custom legal document collection"
}

Smart Suggestions

Get Suggestions


GET /api/knowledge-bases/{id}/suggestions

Get AI-powered document suggestions based on existing content.

Query Parameters:

Parameter	Description
`limit`	Max suggestions to return
`refresh`	Force refresh suggestions

Response:


{
  "suggestions": [
    {
      "document_id": "doc-uuid",
      "document_name": "NDA Template.pdf",
      "suggestion_reason": "Similar to existing contracts",
      "relevance_score": 0.89,
      "gap_analysis": {
        "missing_topics": ["confidentiality", "non-disclosure"],
        "coverage_improvement": 0.15
      }
    }
  ]
}

Check Duplicates


POST /api/knowledge-bases/{id}/suggestions/check-duplicates

Check if documents would be duplicates of existing content.


{
  "document_ids": ["doc1", "doc2"]
}

Response:


{
  "duplicates": [
    {
      "document_id": "doc1",
      "similar_to": "existing-doc-uuid",
      "similarity_score": 0.95
    }
  ],
  "unique": ["doc2"]
}

Knowledge Bases API

Organize documents into knowledge bases for context-aware AI chat and semantic search. See Knowledge Bases and RAG Setup for concepts and chat pipelines.

List Knowledge Bases


GET /api/knowledge-bases

Get all knowledge bases you have access to.

Response


{
  "knowledge_bases": [
    {
      "id": "kb-uuid",
      "name": "Legal Contracts",
      "description": "Collection of client contracts and agreements",
      "document_count": 45,
      "settings": {
        "retrieval": {
          "top_k": 5,
          "threshold": 0.7
        }
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Knowledge Base


POST /api/knowledge-bases

Create a new knowledge base.

Request


{
  "name": "Legal Contracts",
  "description": "Collection of client contracts and agreements",
  "settings": {
    "retrieval": {
      "top_k": 5,
      "threshold": 0.7
    }
  },
  "organization_id": "org-uuid"
}

Field	Type	Required	Description
`name`	string	Yes	Knowledge base name
`description`	string	No	Description
`settings`	object	No	Configuration settings
`organization_id`	string	No	Associate with organization

Settings Options


{
  "retrieval": {
    "top_k": 5,
    "threshold": 0.7,
    "reranking": true
  },
  "chunking": {
    "strategy": "semantic",
    "max_size": 1000,
    "overlap": 100
  }
}

Response


{
  "knowledge_base": {
    "id": "kb-uuid",
    "name": "Legal Contracts",
    "description": "Collection of client contracts and agreements",
    "settings": {...},
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Get Knowledge Base


GET /api/knowledge-bases/{id}

Get a specific knowledge base.

Update Knowledge Base


PATCH /api/knowledge-bases/{id}

Update knowledge base name, description, or settings.


{
  "name": "Updated Name",
  "description": "Updated description",
  "settings": {
    "retrieval": {
      "top_k": 10
    }
  }
}

Delete Knowledge Base


DELETE /api/knowledge-bases/{id}

Delete a knowledge base. Documents are not deleted, only the association.

Documents

List Documents


GET /api/knowledge-bases/{id}/documents

Get all documents in a knowledge base.

Response:


{
  "documents": [
    {
      "id": "doc-uuid",
      "name": "Service Agreement.pdf",
      "status": "completed",
      "file_type": "pdf",
      "created_at": "2024-01-10T00:00:00Z"
    }
  ]
}

Add Document


POST /api/knowledge-bases/{id}/documents

Add an existing document to the knowledge base.


{
  "document_id": "doc-uuid"
}

Batch Add Documents


POST /api/knowledge-bases/{id}/documents/batch

Add multiple documents at once (max 50).


{
  "document_ids": ["doc1", "doc2", "doc3"]
}

Response:


{
  "added": ["doc1", "doc2"],
  "failed": [
    { "id": "doc3", "error": "Document not found" }
  ]
}

Remove Document


DELETE /api/knowledge-bases/{id}/documents?document_id={doc_id}

Remove a document from the knowledge base.

Analytics


GET /api/knowledge-bases/{id}/analytics

Get analytics for a knowledge base.

Query Parameters:

Parameter	Default	Description
`days`	30	Number of days to analyze
`popular_limit`	10	Top N popular queries
`recent_limit`	10	Recent queries to show

Response:


{
  "summary": {
    "total_queries": 150,
    "avg_response_time_ms": 1200,
    "avg_confidence": 0.87,
    "feedback": {
      "positive": 120,
      "negative": 15
    }
  },
  "popular_queries": [
    {
      "query": "payment terms",
      "count": 25,
      "avg_confidence": 0.92
    }
  ],
  "recent_queries": [
    {
      "query": "liability clause",
      "timestamp": "2024-01-15T10:00:00Z",
      "confidence": 0.89
    }
  ],
  "document_usage": [
    {
      "document_id": "doc-uuid",
      "document_name": "Master Agreement.pdf",
      "citation_count": 45
    }
  ]
}

Submit Feedback


POST /api/knowledge-bases/{id}/analytics/feedback

Submit user feedback for chat quality.


{
  "message_id": "msg-uuid",
  "feedback": "thumbs_up"
}

Feedback	Description
`thumbs_up`	Positive - answer was helpful
`thumbs_down`	Negative - answer was not helpful

Templates

List Templates


GET /api/knowledge-bases/templates

Get available knowledge base templates.

Response:


{
  "templates": [
    {
      "id": "template-uuid",
      "name": "Legal Document Library",
      "description": "Pre-configured for legal documents",
      "category": "legal",
      "icon": "scale",
      "is_system_template": true,
      "settings": {...}
    }
  ]
}

Create from Template


POST /api/knowledge-bases/from-template

Create a knowledge base from a template.


{
  "template_id": "template-uuid",
  "name": "My Legal KB",
  "description": "Custom legal document collection"
}

Smart Suggestions

Get Suggestions


GET /api/knowledge-bases/{id}/suggestions

Get AI-powered document suggestions based on existing content.

Query Parameters:

Parameter	Description
`limit`	Max suggestions to return
`refresh`	Force refresh suggestions

Response:


{
  "suggestions": [
    {
      "document_id": "doc-uuid",
      "document_name": "NDA Template.pdf",
      "suggestion_reason": "Similar to existing contracts",
      "relevance_score": 0.89,
      "gap_analysis": {
        "missing_topics": ["confidentiality", "non-disclosure"],
        "coverage_improvement": 0.15
      }
    }
  ]
}

Check Duplicates


POST /api/knowledge-bases/{id}/suggestions/check-duplicates

Check if documents would be duplicates of existing content.


{
  "document_ids": ["doc1", "doc2"]
}

Response:


{
  "duplicates": [
    {
      "document_id": "doc1",
      "similar_to": "existing-doc-uuid",
      "similarity_score": 0.95
    }
  ],
  "unique": ["doc2"]
}