The Knowledge Base Service provides endpoints for creating, managing, and querying document-based knowledge bases. It enables users to create vector stores from multiple document sources, manage documents, and perform semantic search over the stored content.

​
Authentication

All endpoints require a valid Bearer token in the Authorization header.

​
Base URL

/api/kb

​
Knowledge Base Endpoints

​
Create Knowledge Base

Create a new knowledge base in your organization. 
curl -X POST {{baseUrl}}/api/kb/create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Knowledge base for all product documentation and guides",
    "embedding_model": "text-embedding-ada-002",
    "sources": [
      {
        "type": "s3",
        "config": {
          "bucket_name": "docs-bucket",
          "prefix": "product-docs/",
          "aws_access_key_id": "YOUR_ACCESS_KEY",
          "aws_secret_access_key": "YOUR_SECRET_KEY",
          "aws_region": "us-west-2"
        }
      }
    ]
  }'
Endpoint: POST /api/kb/create Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID
Request Body:
FieldTypeRequiredDescription
namestringYesName of the knowledge base
descriptionstringYesDescription of the knowledge base’s purpose
embedding_modelstringYesModel to use for embedding (e.g., “text-embedding-ada-002”)
sourcesarrayYesList of document sources to ingest
Source Configuration: Each source object must have the following fields:
FieldTypeRequiredDescription
typestringYesSource type (e.g., “s3”, “web”, “file”)
configobjectYesConfiguration parameters specific to the source type
Example source configurations: S3 Source: 
{
  "type": "s3",
  "config": {
    "bucket_name": "docs-bucket",
    "prefix": "product-docs/",
    "aws_access_key_id": "YOUR_ACCESS_KEY",
    "aws_secret_access_key": "YOUR_SECRET_KEY",
    "aws_region": "us-west-2"
  }
}
Web Source: 
{
  "type": "web",
  "config": {
    "urls": [
      "https://example.com/docs",
      "https://example.com/faq"
    ]
  }
}
File Upload Source: 
{
  "type": "file",
  "config": {
    "file_ids": [
      "file-123456789",
      "file-987654321"
    ]
  }
}

​
List Knowledge Bases

Retrieve all knowledge bases for an organization. 
curl -X GET {{baseUrl}}/api/kb/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/kb/list Query Parameters:
ParameterRequiredDescription
org_idYesOrganization ID

​
Get Knowledge Base Details

Retrieve detailed information about a specific knowledge base. 
curl -X GET {{baseUrl}}/api/kb/get?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/kb/get Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID

​
Update Knowledge Base

Update an existing knowledge base’s metadata. 
curl -X PUT {{baseUrl}}/api/kb/update?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Documentation",
    "description": "Comprehensive knowledge base for all product documentation and guides"
  }'
Endpoint: PUT /api/kb/update Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
Request Body:
FieldTypeRequiredDescription
namestringNoNew name for the knowledge base
descriptionstringNoNew description

​
Delete Knowledge Base

Delete a knowledge base and all its contents. 
curl -X DELETE {{baseUrl}}/api/kb/delete?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/kb/delete Query Parameters:
ParameterRequiredDescription
kb_idYesID of the knowledge base to delete

​
Document Management Endpoints

​
Add Source to Knowledge Base

Add a new document source to an existing knowledge base. 
curl -X POST {{baseUrl}}/api/kb/add_source?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "web",
    "config": {
      "urls": [
        "https://example.com/docs/new-section",
        "https://example.com/docs/faq"
      ]
    }
  }'
Endpoint: POST /api/kb/add_source Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
Request Body:
FieldTypeRequiredDescription
typestringYesSource type (e.g., “s3”, “web”, “file”)
configobjectYesConfiguration parameters specific to the source type

​
List Documents

List all documents in a knowledge base with pagination. 
curl -X GET "{{baseUrl}}/api/kb/list_documents?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s&page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/kb/list_documents Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
pageNoPage number (default: 1)
limitNoNumber of documents per page (default: 10)
searchNoOptional search term to filter documents

​
Delete Document

Delete a specific document from the knowledge base. 
curl -X DELETE {{baseUrl}}/api/kb/delete_document?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s&document_id=doc-123456789 \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/kb/delete_document Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
document_idYesDocument ID to delete

​
Query Endpoints

​
Search Knowledge Base

Perform a semantic search on the knowledge base. 
curl -X POST {{baseUrl}}/api/kb/search?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I reset my password?",
    "limit": 5,
    "filter": {
      "metadata": {
        "source_type": "faq"
      }
    }
  }'
Endpoint: POST /api/kb/search Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
Request Body:
FieldTypeRequiredDescription
querystringYesSearch query text
limitnumberNoMaximum number of results to return (default: 5)
filterobjectNoMetadata filters to apply to the search

​
RAG Query

Perform a Retrieval-Augmented Generation (RAG) query on the knowledge base. 
curl -X POST {{baseUrl}}/api/kb/query?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I reset my password?",
    "model": "gpt-4",
    "limit": 5,
    "filter": {
      "metadata": {
        "source_type": "faq"
      }
    },
    "params": {
      "temperature": 0.3,
      "include_sources": true
    }
  }'
Endpoint: POST /api/kb/query Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID
Request Body:
FieldTypeRequiredDescription
querystringYesQuery text
modelstringYesLLM model to use (e.g., “gpt-4”, “claude-3-opus”)
limitnumberNoMaximum number of context chunks to retrieve (default: 5)
filterobjectNoMetadata filters to apply to the search
paramsobjectNoAdditional parameters for the LLM
LLM Parameters:
FieldTypeDescription
temperaturenumberSampling temperature (0-1)
include_sourcesbooleanWhether to include source references in the response
system_promptstringCustom system prompt to use with the LLM

​
Status and Monitoring Endpoints

​
Get Ingestion Status

Check the status of document ingestion for a knowledge base. 
curl -X GET {{baseUrl}}/api/kb/ingestion_status?kb_id=9d8e7f6g-5h4i-3j2k-1l0m-9n8o7p6q5r4s \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/kb/ingestion_status Query Parameters:
ParameterRequiredDescription
kb_idYesKnowledge Base ID

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists or conflict with existing resource
500Internal Server Error - Server-side error

​
Implementation Notes

  • Knowledge bases support multiple document sources (S3, web URLs, file uploads)
  • Documents are chunked and embedded for semantic search capability
  • RAG queries combine semantic search with LLM generation for context-aware responses
  • Metadata filters can be used to narrow search results
  • Document ingestion runs as a background process and can be monitored
  • Embeddings are stored in a vector database (PGVector) for efficient similarity search