Knowledge Base API

Manage knowledge base documents, upload content, and perform semantic search against your project's embedded knowledge.

Endpoints

GET

/api/v1/knowledge-base

List all knowledge base documents

GET

/api/v1/knowledge-base/:docId

Get a single document by ID

POST

/api/v1/knowledge-base

Create a new text document

POST

/api/v1/knowledge-base/upload

Upload a file or crawl a URL

POST

/api/v1/knowledge-base/search

Semantic search across documents

DELETE

/api/v1/knowledge-base/:docId

Delete a document and its chunks

List Documents

Returns all knowledge base documents for the project.

Request

GET /api/v1/knowledge-base
Authorization: Bearer cdt_abc123...

Response

{
  "documents": [
    {
      "id": "doc_abc123",
      "name": "Product FAQ",
      "type": "text",
      "status": "ready",
      "chunkCount": 12,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

Create Document

Create a new text document. It will be automatically chunked and embedded.

Request

POST /api/v1/knowledge-base
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "name": "Return Policy",
  "type": "text",
  "content": "Our return policy allows returns within 30 days of purchase..."
}

Response (201)

{
  "id": "doc_xyz789",
  "name": "Return Policy",
  "type": "text",
  "status": "processing"
}

Upload File or URL

Upload a file (PDF, CSV, TXT) via multipart form data, or crawl a URL by passing JSON.

Upload file

POST /api/v1/knowledge-base/upload
Authorization: Bearer cdt_abc123...
Content-Type: multipart/form-data

file: <binary data>

Crawl URL (JSON)

POST /api/v1/knowledge-base/upload
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "name": "Help Center",
  "url": "https://example.com/help"
}

Semantic Search

Search across all documents using natural language. Returns the most relevant chunks ranked by similarity.

Request

POST /api/v1/knowledge-base/search
Authorization: Bearer cdt_abc123...
Content-Type: application/json

{
  "query": "What is the return policy?",
  "topK": 5
}

Response

[
  {
    "content": "Our return policy allows returns within 30 days...",
    "score": 0.92,
    "documentId": "doc_xyz789",
    "documentName": "Return Policy"
  }
]

Parameters

Parameter	Type	Required	Description
name	string	Yes	Document display name
type	string	Yes	text \| url \| pdf \| csv
content	string	For text type	Raw text content
url	string	For URL crawl	Web URL to crawl
query	string	For search	Natural language search query
topK	number	No	Number of results (default: 5)