Knowledge Bases API

Knowledge bases provide context to your agents. Upload text content, files (PDF, TXT, DOC), or URLs that are chunked and vectorized for semantic search during conversations. Knowledge bases are nested under agents.

Base URL: https://kalem.me/api/v1/agents/{agent_id}/knowledge-bases

The Knowledge Base Object

{
  "id": 1,
  "title": "Product FAQ",
  "source_type": "text",
  "status": "completed",
  "is_active": true,
  "content": "Our product supports...",
  "source_reference": null,
  "file_name": null,
  "file_size": null,
  "file_type": null,
  "word_count": 1250,
  "character_count": 7500,
  "processing_error": null,
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:30:00+00:00"
}

Source Types

Type	Description	Processing
`text`	Plain text content provided in the request body	Completes immediately
`file`	Upload a file (PDF, TXT, DOC, DOCX, MD, CSV — max 10MB)	Processed asynchronously
`url`	URL to scrape for content	Processed asynchronously

List Knowledge Bases

GET /api/v1/agents/{agent_id}/knowledge-bases

Query Parameters

Parameter	Type	Description
`status`	string	Filter: `pending`, `processing`, `completed`, `failed`
`source_type`	string	Filter: `text`, `file`, `url`
`search`	string	Search by title
`per_page`	integer	Results per page (default: 15, max: 100)

Example Request

curl -X GET "https://kalem.me/api/v1/agents/1/knowledge-bases?status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch(
  'https://kalem.me/api/v1/agents/1/knowledge-bases?status=completed',
  { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
);
const data = await response.json();

import requests

response = requests.get(
    'https://kalem.me/api/v1/agents/1/knowledge-bases',
    params={'status': 'completed'},
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://kalem.me/api/v1/agents/1/knowledge-bases', [
        'status' => 'completed',
    ]);
$data = $response->json();

Create Knowledge Base

POST /api/v1/agents/{agent_id}/knowledge-bases

Request Body Parameters

Parameter	Type	Required	Description
`title`	string	Required	Title for the knowledge base (max 255)
`source_type`	string	Required	`text`, `file`, or `url`
`content`	string	Required for text	Text content (required when source_type is `text`)
`file`	file	Required for file	File upload: PDF, TXT, DOC, DOCX, MD, CSV (max 10MB)
`source_reference`	string	Required for url	URL to scrape (required when source_type is `url`)

Create Text Knowledge Base

curl -X POST https://kalem.me/api/v1/agents/1/knowledge-bases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product FAQ",
    "source_type": "text",
    "content": "Q: What are your hours? A: We are open 9am-5pm Monday through Friday."
  }'

Create File Knowledge Base

curl -X POST https://kalem.me/api/v1/agents/1/knowledge-bases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "title=Training Manual" \
  -F "source_type=file" \
  -F "file=@/path/to/document.pdf"

Create URL Knowledge Base

curl -X POST https://kalem.me/api/v1/agents/1/knowledge-bases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Docs",
    "source_type": "url",
    "source_reference": "https://example.com/docs"
  }'

Processing: File and URL knowledge bases are processed asynchronously. The initial status will be pending. Poll the GET endpoint to check when processing is completed.

Get Knowledge Base

GET /api/v1/agents/{agent_id}/knowledge-bases/{id}

curl -X GET https://kalem.me/api/v1/agents/1/knowledge-bases/5 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Knowledge Base

PUT /api/v1/agents/{agent_id}/knowledge-bases/{id}

Update a knowledge base's title, content, or active status.

Parameter	Type	Description
`title`	string	Updated title
`content`	string	Updated text content (text type only)
`is_active`	boolean	Enable or disable the knowledge base

curl -X PUT https://kalem.me/api/v1/agents/1/knowledge-bases/5 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated FAQ", "is_active": false}'

Delete Knowledge Base

DELETE /api/v1/agents/{agent_id}/knowledge-bases/{id}

curl -X DELETE https://kalem.me/api/v1/agents/1/knowledge-bases/5 \
  -H "Authorization: Bearer YOUR_API_TOKEN"