6. Knowledge bases

A knowledge base holds indexed documents. Upload files, wait for indexing, then either query for raw retrieved chunks or send a chat request that the platform grounds in your documents. Full lifecycle in one page — this is the biggest step in the walkthrough.

Create a knowledge base

curl -X POST {BASE_URL}/v1/knowledgebases \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "onboarding-notes"}'

{
  "id": "kb_abc123",
  "name": "onboarding-notes",
  "created_at": "2026-09-02T12:35:00Z"
}

Save the id for the next calls:

export KB="kb_abc123"

Upload a file

Send multipart/form-data:

curl -X POST {BASE_URL}/v1/knowledgebases/$KB/files \
  -H "Authorization: Bearer $PAT" \
  -F "file=@handbook.pdf"

{
  "id": "file_xyz789",
  "filename": "handbook.pdf",
  "size": 348192,
  "status": "processing",
  "created_at": "2026-09-02T12:35:30Z"
}

Supported types include PDF, DOCX, TXT, and common images (OCR runs automatically).

Wait for indexing

Indexing runs asynchronously. Poll the file list until every file’s status is ready:

curl {BASE_URL}/v1/knowledgebases/$KB/files \
  -H "Authorization: Bearer $PAT"

{
  "object": "list",
  "data": [
    { "id": "file_xyz789", "filename": "handbook.pdf", "status": "ready", "size": 348192 }
  ]
}

Query for retrieved chunks

Retrieval only — no LLM call. Useful for inspecting what your KB actually contains.

curl -X POST {BASE_URL}/v1/knowledgebases/query \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgebase_ids": ["'$KB'"],
    "query": "What is the process for approving a new vendor?"
  }'

{
  "results": [
    {
      "content": "New vendor approvals require sign-off from the department head and legal review before a purchase order can be issued...",
      "source": { "file_id": "file_xyz789", "filename": "handbook.pdf", "page": 12 },
      "score": 0.87
    }
  ]
}

Chat with the knowledge base (RAG)

Same OpenAI-compatible chat shape as /v1/chat/completions, plus a KB reference. The platform retrieves the relevant chunks and grounds the model’s answer in them.

curl -X POST {BASE_URL}/v1/knowledgebase/chat/completions \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'$CHAT_MODEL'",
    "knowledgebase_ids": ["'$KB'"],
    "messages": [
      {"role": "user", "content": "Summarize our vendor approval process."}
    ]
  }'

{
  "id": "chatcmpl-rag-abc",
  "object": "chat.completion",
  "model": "llama3.2:3b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Vendor approvals require department-head sign-off followed by a legal review before any purchase order is issued. Approval is expected within five business days."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 210, "completion_tokens": 42, "total_tokens": 252 }
}

This endpoint is stateless too — send the full messages[] on every turn. The server injects fresh KB context each call. Next: Research →

Getting Started

Guides

API Walkthrough

Create a knowledge base

Upload a file

Wait for indexing

Query for retrieved chunks

Chat with the knowledge base (RAG)

​Create a knowledge base

​Upload a file

​Wait for indexing

​Query for retrieved chunks

​Chat with the knowledge base (RAG)

Create a knowledge base

Upload a file

Wait for indexing

Query for retrieved chunks

Chat with the knowledge base (RAG)