# Knowledge Bases

Store business reference information in Knowledge Bases and link them to Assistants. Each Knowledge Base groups related Knowledge items, such as policies, product details, or opening hours.

## Overview

A "Return Policy" Knowledge Base might contain "Standard Returns", "Sale Items", and "International Orders" items. Each item has a title, content, and an `available` flag that controls whether the Assistant receives it.

When a conversation starts, Reecall adds the available items from the Assistant's linked Knowledge Bases to its conversation context.

:::info{title="Note"}

You can link the same Knowledge Base to multiple Assistants. For instance, if you have a "Product Catalogue" Knowledge Base, both your "Sales Assistant" and "Support Assistant" can use it without duplicating the content.

:::

### Why use Knowledge Bases?

Use Knowledge Bases to manage reference information separately from the Assistant's behaviour instructions:

* **Structured data management**: Organise information into logical groups with clear titles and descriptions
* **Granular control**: Enable or disable individual Knowledge items using the `available` flag without editing instructions
* **Separation of concerns**: Keep your Assistant's behaviour instructions separate from reference data
* **Easier maintenance**: Update Knowledge content independently from core instructions
* **Reusability**: Link the same Knowledge Base to multiple Assistants

<Mermaid chart={`flowchart TD
    subgraph KB["knowledgeBase: Return Policy"]
        direction TB
        K1["knowledge<br>{ title: 'Standard Returns', content: '30 days, unused items...' }"]
        K2["knowledge<br>{ title: 'Damaged Items', content: 'Report within 48h...' }"]
    end
    
    A1["Sales Assistant"] --> KB
    A2["Support Assistant"] --> KB`} />

## Data model

### Knowledge Base

A Knowledge Base groups related Knowledge items under a common name and description.

| Field            | Type     | Required       | Description                                                                            |
| ---------------- | -------- | -------------- | -------------------------------------------------------------------------------------- |
| `id`             | uuid     | Auto-generated | Unique identifier                                                                      |
| `name`           | string   | No            | A descriptive identifier for the Knowledge Base (e.g., "Products", "Company Policies") |
| `description`    | string   | No            | Context explaining what the Knowledge Base contains                                    |
| `projectId`      | uuid     | Auto-set       | The Project this Knowledge Base belongs to                                             |
| `organizationId` | uuid     | Auto-set       | The Organisation this Knowledge Base belongs to                                        |
| `createdAt`      | datetime | Auto-generated | Creation timestamp                                                                     |
| `updatedAt`      | datetime | Auto-generated | Last update timestamp                                                                  |

**Example:**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Administrative",
  "description": "Regroup opening hours, addresses, email and other administrative information",
  "projectId": "...",
  "organizationId": "...",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

### Knowledge

A Knowledge item represents a single piece of information within a Knowledge Base.

| Field             | Type     | Required       | Description                                                                                |
| ----------------- | -------- | -------------- | ------------------------------------------------------------------------------------------ |
| `id`              | uuid     | Auto-generated | Unique identifier                                                                          |
| `title`           | string   | Yes            | A short, descriptive name for the Knowledge item                                           |
| `content`         | string   | Yes            | The actual information the Assistant can reference                                         |
| `available`       | boolean  | No             | When `true` (default), the item is provided to the Assistant; when `false`, it is excluded |
| `knowledgeBaseId` | uuid     | Yes            | Reference to the parent Knowledge Base                                                     |
| `projectId`       | uuid     | Auto-set       | The Project this Knowledge belongs to                                                      |
| `organizationId`  | uuid     | Auto-set       | The Organisation this Knowledge belongs to                                                 |
| `createdAt`       | datetime | Auto-generated | Creation timestamp                                                                         |
| `updatedAt`       | datetime | Auto-generated | Last update timestamp                                                                      |

**Example:**

```json
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "title": "Hours",
  "content": "Lundi-Vendredi 8h-12h, 14h-18h",
  "available": true,
  "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
  "projectId": "...",
  "organizationId": "...",
  "createdAt": "2025-01-15T10:35:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}
```

## Workflow

Use a project-scoped API key, or include `projectId` in creation payloads with an organization-scoped key. Send `Authorization: Bearer <your-api-key>` on every request below. The paths are relative to the Data API server URL in the [API reference](/api), which includes `/data_next`.

### Step 1: create a Knowledge Base

Create a Knowledge Base to group related information:

```http
POST /ai/knowledgeBases
Content-Type: application/json

{
  "name": "Return Policy",
  "description": "Rules and procedures for product returns"
}
```

### Step 2: add Knowledge items

Save the Knowledge Base's returned `id` and pass it as `knowledgeBaseId` when creating items. The examples use `550e8400-e29b-41d4-a716-446655440000` as that ID:

```http
POST /ai/knowledges
Content-Type: application/json

{
  "title": "Standard Returns",
  "content": "Customers can return items within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "available": true,
  "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Step 3: link to an Assistant

Link the Knowledge Base to an Assistant so it can access the information during conversations. Update the Assistant's `knowledgeBaseIds` field with the IDs of the Knowledge Bases you want to attach:

```http
PATCH /conversational/assistants/{assistantId}
Content-Type: application/json

{
  "knowledgeBaseIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

:::info{title="Note"}

You can link multiple Knowledge Bases to a single Assistant by adding multiple IDs to the array.

:::

## How the Assistant uses Knowledge Bases

The Assistant receives items with `available: true` from its linked Knowledge Bases in its context. It can use this information to answer questions about pricing, policies, or procedures and follow the business rules you provide. Items with `available: false` are excluded.

## Limitations

Knowledge Bases have these content and item limits:

| Constraint                          | Limit          |
| ----------------------------------- | -------------- |
| Knowledge `title` length            | 100 characters |
| Knowledge `content` length          | 400 characters |
| Items per Knowledge Base            | 50 items       |
| Assistant `knowledgeBaseIds` length | 3 items        |

An Assistant can access up to **150 Knowledge items** across three Knowledge Bases. Split content longer than 400 characters into focused items within these limits. For content beyond the per-Assistant limit, use specialised Assistants for different domains.

## Best practices

### Organising Knowledge Bases

* **Group logically**: Create Knowledge Bases that reflect how information is naturally organised in your business
* **Keep focused**: Each Knowledge Base should cover a distinct topic area
* **Use clear names**: The `name` field should immediately convey what information is contained
* **Write descriptive summaries**: The `description` field helps both humans and the system understand the purpose

### Writing effective content

* **Be specific**: Include concrete details the Assistant might need (prices, dates, names)
* **Keep items focused**: One Knowledge item should cover one topic
* **Use clear formatting**: Structure content so key information is easy to identify
* **Update regularly**: Keep Knowledge current to avoid outdated responses

### Example structure

**Knowledge Base:**

```json
{
  "name": "Return Policy",
  "description": "Rules and procedures for product returns"
}
```

**Knowledge items:**

```json
[
  {
    "title": "Standard Returns",
    "content": "Customers can return items within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
    "available": true,
    "knowledgeBaseId": "..."
  },
  {
    "title": "Sale Items",
    "content": "Items purchased during promotional sales are final sale and cannot be returned or exchanged.",
    "available": true,
    "knowledgeBaseId": "..."
  }
]
```

## Using the `available` flag

Set `available` to `false` to exclude an item from subsequent conversations without deleting it. Use this to:

* **Temporarily disable items** without deleting them
* **Prepare new content** before making it live
* **Exclude outdated information** from subsequent conversations
* **Test different Knowledge configurations**

Only items with `available: true` (the default) are provided to the Assistant during conversations.
