Knowledge Base Service API

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Introduction

Getting Started

Architecture

Authentication

API Reference

Development Guides

Troubleshooting

Knowledge Base Service API

Authentication

Base URL

Knowledge Base Endpoints

Create Knowledge Base

List Knowledge Bases

Get Knowledge Base Details

Update Knowledge Base

Delete Knowledge Base

Document Management Endpoints

Add Source to Knowledge Base

List Documents

Delete Document

Query Endpoints

Search Knowledge Base

RAG Query

Status and Monitoring Endpoints

Get Ingestion Status

Error Responses

Implementation Notes

Introduction

Getting Started

Architecture

Authentication

API Reference

Development Guides

Troubleshooting

​Authentication

​Base URL

​Knowledge Base Endpoints

​Create Knowledge Base

​List Knowledge Bases

​Get Knowledge Base Details

​Update Knowledge Base

​Delete Knowledge Base

​Document Management Endpoints

​Add Source to Knowledge Base

​List Documents

​Delete Document

​Query Endpoints

​Search Knowledge Base

​RAG Query

​Status and Monitoring Endpoints

​Get Ingestion Status

​Error Responses

​Implementation Notes

Authentication

Base URL

Knowledge Base Endpoints

Create Knowledge Base

List Knowledge Bases

Get Knowledge Base Details

Update Knowledge Base

Delete Knowledge Base

Document Management Endpoints

Add Source to Knowledge Base

List Documents

Delete Document

Query Endpoints

Search Knowledge Base

RAG Query

Status and Monitoring Endpoints

Get Ingestion Status

Error Responses

Implementation Notes