Documentation
API Reference
REST API for Clara AI. All endpoints require an API key unless marked otherwise.
Authentication
Pass your API key in the x-api-key header on every request.
curl -H "x-api-key: YOUR_API_KEY" https://{your-org}.clara.ai/api/kbs
Knowledge Bases
GET
/api/kbsAuth requiredList all knowledge bases for your org
Response
{ "kbs": [{ "id": "kb_xxx", "name": "Support Docs", "doc_count": 42 }] }POST
/api/kbsAuth requiredCreate a new knowledge base
Request body
namestringrequiredHuman-readable namedescriptionstringoptionalOptional descriptionResponse
{ "kb": { "id": "kb_xxx", "name": "Support Docs", "created_at": "2025-01-01T00:00:00Z" } }DELETE
/api/kbs/:idAuth requiredDelete a knowledge base and all its documents
Response
{ "success": true }Documents & Ingestion
GET
/api/kbs/:id/documentsAuth requiredList documents in a knowledge base
Response
{ "documents": [{ "id": "doc_xxx", "filename": "policy.pdf", "status": "ready", "chunk_count": 24 }] }POST
/api/ingest/uploadAuth requiredUpload a file for ingestion (multipart/form-data)
Request body
fileFilerequiredPDF, DOCX, TXT, or MD filekb_idstringrequiredTarget knowledge base IDResponse
{ "document": { "id": "doc_xxx", "status": "processing" } }POST
/api/ingest/urlAuth requiredIngest content from a URL
Request body
urlstringrequiredPublic URL to crawl and ingestkb_idstringrequiredTarget knowledge base IDResponse
{ "document": { "id": "doc_xxx", "status": "processing" } }RAG Search & Chat
POST
/api/rag/searchAuth requiredRun a RAG query against a knowledge base
Request body
querystringrequiredThe user's questionkb_idstringrequiredKnowledge base to searchtop_knumberoptionalNumber of chunks to retrieve (default: 5)streambooleanoptionalStream response via SSE (default: false)Response
{ "answer": "Yes, burst pipes are covered...", "citations": [{ "doc_id": "doc_xxx", "score": 0.92 }] }POST
/api/rag/chatAuth requiredMulti-turn chat with memory (session-based)
Request body
messagestringrequiredUser messagekb_idstringrequiredKnowledge base IDsession_idstringoptionalConversation session ID for memoryResponse
{ "response": "...", "session_id": "sess_xxx", "citations": [] }