> ## Documentation Index
> Fetch the complete documentation index at: https://docs.co-mind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 6. Knowledge bases

> Create a knowledge base, upload files, query it for context, and chat with retrieval-augmented generation.

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

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

```json theme={null}
{
  "id": "kb_abc123",
  "name": "onboarding-notes",
  "created_at": "2026-09-02T12:35:00Z"
}
```

Save the id for the next calls:

```bash theme={null}
export KB="kb_abc123"
```

## Upload a file

Send `multipart/form-data`:

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

```json theme={null}
{
  "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`:

```bash theme={null}
curl {BASE_URL}/v1/knowledgebases/$KB/files \
  -H "Authorization: Bearer $PAT"
```

```json theme={null}
{
  "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.

```bash theme={null}
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?"
  }'
```

```json theme={null}
{
  "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.

```bash theme={null}
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."}
    ]
  }'
```

```json theme={null}
{
  "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 →](/guides/api-walkthrough/research)