# Knowledge bases

A knowledge base holds documents an AI agent can search during a call (its built-in `search_knowledge` tool).
Documents are pasted text, a web page, or an uploaded text file. Each document is split into chunks and embedded;
it is `processing` until that finishes. Attach knowledge bases to an agent with `agent.knowledge_base_ids`
(up to 5) on the [voice app](/guides/voice-apps.md).

Auth, errors, paging and idempotency work as described in the [overview](/guides/overview.md).

Base URL: `https://api.contactivity.io/v1/projects/{project_id}`

| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | `/knowledge-bases` | `apps:read` | List knowledge bases |
| POST | `/knowledge-bases` | `apps:write` | Create one |
| GET | `/knowledge-bases/{id}` | `apps:read` | Fetch one with its documents |
| PATCH | `/knowledge-bases/{id}` | `apps:write` | Rename or describe it |
| DELETE | `/knowledge-bases/{id}` | `apps:write` | Archive it (excluded from search) |
| POST | `/knowledge-bases/{id}/documents` | `apps:write` | Add a document |
| DELETE | `/knowledge-bases/{id}/documents/{doc_id}` | `apps:write` | Archive a document |
| GET | `/knowledge-bases/{id}/search?q=` | `apps:read` | The 5 closest chunks |

Limits: 20 knowledge bases per project, 100 documents per knowledge base, 1,000,000 characters per document.

## Objects

Knowledge base:

| Field | Type | Notes |
|---|---|---|
| `id` | string | `kb_…` |
| `name` | string | 1-100 characters |
| `description` | string | Up to 1000 characters |
| `documents` | integer, or array | A count in list/create/update responses; the document objects (oldest first) on fetch |
| `created_at`, `updated_at` | timestamp | |

Document:

| Field | Type | Notes |
|---|---|---|
| `id` | string | `kbd_…` |
| `name` | string | Up to 200 characters (longer names are cut) |
| `source` | string | `text`, `url` or `file` |
| `source_url` | string or null | For `url` |
| `content_type` | string or null | e.g. `text/plain`, `text/html` |
| `status` | string | `processing`, `ready` or `error` |
| `error` | string or null | Why ingest failed |
| `chars`, `chunks` | integer or null | Size once ingested |
| `created_at` | timestamp | |

## Create, update, archive

```sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Clinic FAQ", "description": "Opening hours, parking, insurance"}'
```

| Field | Type | Required | Limits |
|---|---|---|---|
| `name` | string | create: yes | 1-100 characters |
| `description` | string | no | up to 1000 characters |

`POST` returns `201`. `PATCH /knowledge-bases/{id}` takes the same fields; fields left out keep their values.
`DELETE` archives the knowledge base (its documents leave search) and returns `204`; it is refused while an AI
agent's draft lists the knowledge base.

Errors: `400 invalid_parameter` (`name`, `description`, or the 20-per-project limit), `400 unknown_parameter`,
`400 invalid_json`, `404 not_found`, `409 conflict` (delete: used by an agent).

## Add a document

JSON with `name` and `text`, or `url` (and optional `name`, default the URL). Exactly one of `text` or `url`.

```sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/documents \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hours", "text": "We are open Monday to Friday, 8 am to 6 pm."}'
```

Or upload a file (`multipart/form-data`, field `file`, optional `name`): UTF-8 `.txt`, `.md`, `.csv`, `.json`,
`.html` or `.htm`, up to 5 MB. HTML is reduced to its text. PDF and DOCX are not supported yet.

```sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/documents \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -F file=@faq.md
```

Returns `202` with the document in `processing`. Fetch the knowledge base to see it become `ready` (or `error`).

Errors: `400 invalid_parameter` (`name`, `url`, `file`; neither or both of text and url; empty or too long
document; 100-document limit), `400 unknown_parameter`, `400 invalid_json`, `404 not_found`,
`503 service_unavailable` (could not queue the document; add it again).

`DELETE /knowledge-bases/{id}/documents/{doc_id}` archives the document (excluded from search) and returns `204`.
Errors: `404 not_found`, `409 archived`.

## Search

`GET /knowledge-bases/{id}/search?q=...` returns the 5 chunks closest to `q` (1-1000 characters), best first, as
one page: `{data: [{document, content, score}], has_more: false, next_cursor: null}`. `score` is the cosine
similarity. Use it to check what an agent will find.

```sh
curl -G https://api.contactivity.io/v1/projects/$PROJECT_ID/knowledge-bases/kb_us1_abc/search \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  --data-urlencode "q=when are you open"
```

Errors: `400 invalid_parameter` (`q`), `404 not_found`, `502 upstream_error` (the embedding provider failed).