Knowledge Base Service API

API reference for managing knowledge bases and vector stores

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.

Request

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:

Parameter	Required	Description
org_id	Yes	Organization ID

Request Body:

Field	Type	Required	Description
name	string	Yes	Name of the knowledge base
description	string	Yes	Description of the knowledge base’s purpose
embedding_model	string	Yes	Model to use for embedding (e.g., “text-embedding-ada-002”)
sources	array	Yes	List of document sources to ingest

Source Configuration:

Each source object must have the following fields:

Field	Type	Required	Description
type	string	Yes	Source type (e.g., “s3”, “web”, “file”)
config	object	Yes	Configuration 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.

Request

curl -X GET {{baseUrl}}/api/kb/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/kb/list

Query Parameters:

Parameter	Required	Description
org_id	Yes	Organization ID

Get Knowledge Base Details

Retrieve detailed information about a specific knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Update Knowledge Base

Update an existing knowledge base’s metadata.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Request Body:

Field	Type	Required	Description
name	string	No	New name for the knowledge base
description	string	No	New description

Delete Knowledge Base

Delete a knowledge base and all its contents.

Request

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:

Parameter	Required	Description
kb_id	Yes	ID of the knowledge base to delete

Document Management Endpoints

Add Source to Knowledge Base

Add a new document source to an existing knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Request Body:

Field	Type	Required	Description
type	string	Yes	Source type (e.g., “s3”, “web”, “file”)
config	object	Yes	Configuration parameters specific to the source type

List Documents

List all documents in a knowledge base with pagination.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID
page	No	Page number (default: 1)
limit	No	Number of documents per page (default: 10)
search	No	Optional search term to filter documents

Delete Document

Delete a specific document from the knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID
document_id	Yes	Document ID to delete

Query Endpoints

Search Knowledge Base

Perform a semantic search on the knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Request Body:

Field	Type	Required	Description
query	string	Yes	Search query text
limit	number	No	Maximum number of results to return (default: 5)
filter	object	No	Metadata filters to apply to the search

RAG Query

Perform a Retrieval-Augmented Generation (RAG) query on the knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Request Body:

Field	Type	Required	Description
query	string	Yes	Query text
model	string	Yes	LLM model to use (e.g., “gpt-4”, “claude-3-opus”)
limit	number	No	Maximum number of context chunks to retrieve (default: 5)
filter	object	No	Metadata filters to apply to the search
params	object	No	Additional parameters for the LLM

LLM Parameters:

Field	Type	Description
temperature	number	Sampling temperature (0-1)
include_sources	boolean	Whether to include source references in the response
system_prompt	string	Custom system prompt to use with the LLM

Status and Monitoring Endpoints

Get Ingestion Status

Check the status of document ingestion for a knowledge base.

Request

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:

Parameter	Required	Description
kb_id	Yes	Knowledge Base ID

Error Responses

Status Code	Description
400	Bad Request - Invalid input or validation error
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists or conflict with existing resource
500	Internal 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