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

# Knowledge Bases

# Knowledge Bases

Manage knowledge bases that agents can reference during calls. Creating a knowledge base is a two-step process:

1. **Create** the knowledge base (name + description only).
2. **Add sources** — upload files, paste text, or crawl URLs. Each source is indexed independently and has its own `status`.

For UUID / phone / datetime formats used below, see [Data formats](/api-reference/introduction#data-formats).

***

## List Knowledge Bases

<Endpoint method="GET" path="/api/public/v1/knowledge-bases" />

### Parameters

**Query parameters:**

| Parameter | Type    | Default | Description                                       |
| --------- | ------- | ------- | ------------------------------------------------- |
| `name`    | string  | —       | Filter by name (case-insensitive substring match) |
| `limit`   | integer | `50`    | 1–100                                             |
| `offset`  | integer | `0`     | Pagination offset                                 |

Returns `data` (array of knowledge base objects), `pagination`, and `meta`.

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Get Knowledge Base

<Endpoint method="GET" path="/api/public/v1/knowledge-bases/{kb_id}" />

Returns `data` (knowledge base object) and `meta`.

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Create Knowledge Base

<Endpoint method="POST" path="/api/public/v1/knowledge-bases" />

Create an empty knowledge base. Add content via [Add Document Source](#add-document-source) or [Add Web Source](#add-web-source) after creation.

### Parameters

**Request body:**

| Field         | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `name`        | string | **Yes**  | Display name for the knowledge base |
| `description` | string | No       | Optional description                |

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ",
    "description": "Frequently asked questions"
  }'
```

**Response:** 201 Created with `data` (knowledge base object, `status: "ready"`) and `meta`.

***

## Update Knowledge Base

<Endpoint method="PATCH" path="/api/public/v1/knowledge-bases/{kb_id}" />

Update the name or description. Only included fields are changed. To update content, add or delete sources.

### Parameters

**Request body:**

| Field         | Type   | Description      |
| ------------- | ------ | ---------------- |
| `name`        | string | New display name |
| `description` | string | New description  |

### cURL

```bash theme={null}
curl -X PATCH "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ - Updated",
    "description": "Revised Q&A content"
  }'
```

***

## Delete Knowledge Base

<Endpoint method="DELETE" path="/api/public/v1/knowledge-bases/{kb_id}" />

Permanently deletes the knowledge base, all its sources, and removes it from Ultravox. Agents that reference this knowledge base will no longer have access to it.

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## List Sources

<Endpoint method="GET" path="/api/public/v1/knowledge-bases/{kb_id}/sources" />

List all sources attached to a knowledge base. Source statuses are synced in real-time. Poll this endpoint every 5–10 seconds while any source has `status: "scanning"` to track indexing progress.

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": "3a1bc2d4-0000-4000-8000-000000000001",
      "kb_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
      "name": "Company FAQ",
      "description": null,
      "kind": "document",
      "status": "ready",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:01:00Z"
    }
  ],
  "meta": { "request_id": "...", "ts": "2024-01-01T00:00:00Z" }
}
```

***

## Add Document Source

<Endpoint method="POST" path="/api/public/v1/knowledge-bases/{kb_id}/sources/document" />

Upload a file (PDF, TXT, DOCX, or Markdown) as a source. The file is base64-encoded in the request body. Maximum file size: 50 MB.

### Parameters

**Request body:**

| Field         | Type   | Required | Description                  |
| ------------- | ------ | -------- | ---------------------------- |
| `name`        | string | **Yes**  | Display name for this source |
| `description` | string | No       | Optional description         |
| `file`        | object | **Yes**  | File to upload (see below)   |

**`file` object:**

| Field          | Type   | Description                                                                                                                            |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`     | string | File name including extension (e.g. `policy.pdf`)                                                                                      |
| `data`         | string | Base64-encoded file content                                                                                                            |
| `content_type` | string | MIME type: `application/pdf`, `text/plain`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `text/markdown` |

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "description": "Our standard 30-day return policy",
    "file": {
      "filename": "return-policy.pdf",
      "data": "JVBERi0xLjQKJcfs...",
      "content_type": "application/pdf"
    }
  }'
```

**Response:** 201 Created with `data` (source object with initial `status: "scanning"`) and `meta`. Poll [List Sources](#list-sources) until `status` becomes `ready` or `failed`.

***

## Add Web Source

<Endpoint method="POST" path="/api/public/v1/knowledge-bases/{kb_id}/sources/web" />

Crawl one or more URLs and index their content as a source. The crawler follows links up to `max_depth` levels.

### Parameters

**Request body:**

| Field         | Type      | Required | Description                                                                      |
| ------------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `name`        | string    | **Yes**  | Display name for this source                                                     |
| `description` | string    | No       | Optional description                                                             |
| `urls`        | string\[] | **Yes**  | One or more URLs to crawl                                                        |
| `max_depth`   | integer   | No       | Link-follow depth. `0` = page only, `1` = one level of links (default). Max `3`. |

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/web" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center",
    "description": "Indexed from our help site",
    "urls": [
      "https://help.example.com/faq",
      "https://help.example.com/pricing",
      "https://help.example.com/getting-started"
    ],
    "max_depth": 1
  }'
```

**Response:** 201 Created with `data` (source object with initial `status: "scanning"`) and `meta`. Poll [List Sources](#list-sources) until `status` becomes `ready` or `failed`.

***

## Delete Source

<Endpoint method="DELETE" path="/api/public/v1/knowledge-bases/{kb_id}/sources/{source_id}" />

Remove a source from a knowledge base. The indexed content for this source is permanently deleted from Ultravox.

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/knowledge-bases/6f4af8be-0a96-49b0-ac2a-a359f46cc966/sources/3a1bc2d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

***

## Knowledge Base Object

| Field         | Type     | Description                                              |
| ------------- | -------- | -------------------------------------------------------- |
| `id`          | UUID     | Knowledge base ID                                        |
| `name`        | string   | Display name                                             |
| `description` | string   | Optional description                                     |
| `status`      | string   | `ready` — available to agents; `creating` — being set up |
| `language`    | string   | Content language (e.g. `en-US`)                          |
| `created_at`  | datetime | When the knowledge base was created                      |
| `updated_at`  | datetime | Last updated                                             |

## Source Object

| Field         | Type     | Description                                                                                               |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `id`          | UUID     | Source ID                                                                                                 |
| `kb_id`       | UUID     | Parent knowledge base ID                                                                                  |
| `name`        | string   | Display name                                                                                              |
| `description` | string   | Optional description                                                                                      |
| `kind`        | string   | `document` (file upload) or `web` (URL crawl)                                                             |
| `status`      | string   | `pending` — queued; `scanning` — indexing in progress; `ready` — fully indexed; `failed` — indexing error |
| `created_at`  | datetime | When the source was added                                                                                 |
| `updated_at`  | datetime | Last updated                                                                                              |

## Full Example — Create KB and Add Sources

```bash theme={null}
# Step 1: Create the knowledge base
KB_ID=$(curl -s -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer Support KB"}' | jq -r '.data.id')

# Step 2a: Add a PDF document
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources/document" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Product Manual\",
    \"file\": {
      \"filename\": \"manual.pdf\",
      \"data\": \"$(base64 -i manual.pdf)\",
      \"content_type\": \"application/pdf\"
    }
  }"

# Step 2b: Add a web crawl source
curl -X POST "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources/web" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Help Center",
    "urls": ["https://help.example.com/faq"],
    "max_depth": 1
  }'

# Step 3: Poll until all sources are ready
curl "https://api.truedy.ai/api/public/v1/knowledge-bases/$KB_ID/sources" \
  -H "Authorization: Bearer YOUR_API_KEY"
```