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

# Knowledge Bases

> Create, manage, and link knowledge bases to agents for RAG-powered responses.

# Knowledge Bases

Knowledge bases store documents, URLs, and structured data that agents use for retrieval-augmented generation (RAG). Each KB has its own vector index, document registry, and optional knowledge graph.

<Note>
  All API requests require a valid JWT token in the `Authorization: Bearer <token>` header. The API Gateway decodes the JWT and forwards auth context (`user-id`, `organization-id`, `user-email`, `x-platform-role`, `x-org-role`) as headers to downstream services.
</Note>

## Create Knowledge Base

<ParamField method="POST" path="/api/knowledge/kb" />

Create a new knowledge base in your organization.

### Request Body

<ParamField body="name" type="string" required>
  Knowledge base name.
</ParamField>

<ParamField body="description" type="string">
  Description of the knowledge base contents.
</ParamField>

<ParamField body="visibility" type="string" default="private">
  Visibility: `private`, `shared`, or `public`.
</ParamField>

<ParamField body="settings" type="object">
  Custom KB settings (embedding config, chunking strategy, etc.).
</ParamField>

### Response (201)

<ResponseField name="knowledgeBase" type="object">
  The created knowledge base.

  <Expandable title="Knowledge base object">
    <ResponseField name="id" type="string">KB UUID.</ResponseField>
    <ResponseField name="name" type="string">KB name.</ResponseField>
    <ResponseField name="description" type="string">KB description.</ResponseField>
    <ResponseField name="organizationId" type="string">Owning organization UUID.</ResponseField>
    <ResponseField name="visibility" type="string">Visibility level.</ResponseField>
    <ResponseField name="settings" type="object">KB settings.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://your-domain.com/api/knowledge/kb \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Help Center Articles",
      "description": "Customer support documentation",
      "visibility": "shared"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://your-domain.com/api/knowledge/kb", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Help Center Articles",
      description: "Customer support documentation",
      visibility: "shared",
    }),
  });

  const { knowledgeBase } = await response.json();
  ```
</CodeGroup>

***

## List Knowledge Bases

<ParamField method="GET" path="/api/knowledge/kb" />

List all knowledge bases in your organization.

### Query Parameters

<ParamField query="limit" type="number" default="50">Maximum results.</ParamField>
<ParamField query="offset" type="number" default="0">Pagination offset.</ParamField>

### Response (200)

<ResponseField name="knowledgeBases" type="object[]">Array of KB objects.</ResponseField>
<ResponseField name="total" type="number">Total count.</ResponseField>
<ResponseField name="limit" type="number">Applied limit.</ResponseField>
<ResponseField name="offset" type="number">Applied offset.</ResponseField>

```bash curl theme={null}
curl https://your-domain.com/api/knowledge/kb?limit=20 \
  -H "Authorization: Bearer $TOKEN"
```

***

## Get Knowledge Base

<ParamField method="GET" path="/api/knowledge/kb/:id" />

Get a single knowledge base with full details.

### Path Parameters

<ParamField path="id" type="string" required>KB UUID.</ParamField>

### Response (200)

<ResponseField name="knowledgeBase" type="object">Full KB object.</ResponseField>

***

## Update Knowledge Base

<ParamField method="PATCH" path="/api/knowledge/kb/:id" />

Update knowledge base metadata.

### Path Parameters

<ParamField path="id" type="string" required>KB UUID.</ParamField>

### Request Body

<ParamField body="name" type="string">Updated name.</ParamField>
<ParamField body="description" type="string">Updated description.</ParamField>
<ParamField body="visibility" type="string">Updated visibility.</ParamField>
<ParamField body="settings" type="object">Updated settings.</ParamField>

### Response (200)

Returns the updated KB object.

***

## Delete Knowledge Base

<ParamField method="DELETE" path="/api/knowledge/kb/:id" />

Permanently delete a knowledge base, including all documents, chunks, vectors, and graph data.

### Path Parameters

<ParamField path="id" type="string" required>KB UUID.</ParamField>

### Response (204)

No content on success.

<Warning>
  This action is irreversible. All documents, embeddings, and knowledge graph data for this KB will be permanently deleted.
</Warning>

***

## Link Agent to KB

<ParamField method="POST" path="/api/knowledge/kb/:id/agents/:agentId" />

Link a knowledge base to an agent, enabling RAG context retrieval for that agent's conversations.

### Path Parameters

<ParamField path="id" type="string" required>KB UUID.</ParamField>
<ParamField path="agentId" type="string" required>Agent UUID.</ParamField>

### Request Body

<ParamField body="permissions" type="object">
  Optional permission overrides for this link.
</ParamField>

<ParamField body="priority" type="number" default="0">
  Priority level for search result ranking when multiple KBs are linked.
</ParamField>

### Response (200)

```json theme={null}
{
  "message": "Agent linked to knowledge base successfully",
  "knowledgeBaseId": "kb-uuid",
  "agentId": "agent-uuid"
}
```

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/agents/AGENT_ID \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"priority": 1}'
  ```

  ```javascript JavaScript theme={null}
  await fetch(
    `https://your-domain.com/api/knowledge/kb/${kbId}/agents/${agentId}`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ priority: 1 }),
    }
  );
  ```
</CodeGroup>

***

## Unlink Agent from KB

<ParamField method="DELETE" path="/api/knowledge/kb/:id/agents/:agentId" />

Remove the link between a knowledge base and an agent.

### Path Parameters

<ParamField path="id" type="string" required>KB UUID.</ParamField>
<ParamField path="agentId" type="string" required>Agent UUID.</ParamField>

### Response (200)

```json theme={null}
{
  "message": "Agent unlinked successfully"
}
```

***

## Get Agent's Linked KBs

<ParamField method="GET" path="/api/knowledge/agents/:agentId/kbs" />

Get all knowledge bases linked to a specific agent.

### Path Parameters

<ParamField path="agentId" type="string" required>Agent UUID.</ParamField>

### Response (200)

<ResponseField name="knowledgeBases" type="object[]">
  Array of KB objects with link metadata (permissions, priority, linked\_at).
</ResponseField>

<ResponseField name="count" type="number">Number of linked KBs.</ResponseField>