# client.kb_documents

> The kb_documents methods of the morevoice Python SDK: Knowledge-base documents assistants answer from.

Knowledge-base documents assistants answer from. These methods are on `client.kb_documents`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `create()`

**Add a knowledge-base document.** Adds a document from a file (JSON with base64, or multipart/form-data with a `file` part, ≤ 25 MB), a public URL, or text, and indexes it in the background: answers 202 with the document `pending`. Poll it until `status` is `ready` (searchable) or `error`. Beyond the plan's knowledge-base storage: 402 plan_limit.

```python
# client.kb_documents
def create(self, body: _m.KbDocumentCreateParamsInput | _m.KbDocumentsCreateFilesBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.KbDocument
```

`client.kb_documents.create()` · `await async_client.kb_documents.create()` · `POST /kb/documents` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_create/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `object` | no | A file to upload. Or send the request as multipart/form-data with a `file` part. |
| `format` | `"md" \| "txt" \| "csv"` | no | With `text`: how to read it (default md). |
| `text` | `string` | no | Text to index as it is. |
| `title` | `string` | no | Default: the file's name, the page's title, or (text) "Document". |
| `url` | `string` | no | A public web page or file (http/https) to fetch and index. It is fetched again on reingest. |

### Returns

`KbDocument`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The document's ID. |
| `object` | `"kb_document"` | Always `kb_document`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `title` | `string` | — |
| `kind` | `"pdf" \| "docx" \| "md" \| "txt" \| "csv" \| "xlsx" \| "html" \| "url"` | The format it was read as; `url` for a web page. |
| `source` | `string` | The uploaded file's name, or the URL. |
| `status` | `"pending" \| "processing" \| "ready" \| "error"` | pending → processing → ready (searchable) \| error. Poll the document, or follow `kb.document.*` events. |
| `error` | `string \| null` | Why ingestion failed (status error). |
| `bytes` | `integer` | — |
| `chunk_count` | `integer` | Searchable passages the document was split into. |
| `original_stored` | `boolean` | The original file is kept (encrypted): GET …/content downloads it and reingest re-reads it. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

kb_document = client.kb_documents.create({
    "text": "# Opening hours\nSunday–Thursday 08:00–18:00, Friday 08:00–13:00.",
    "title": "Opening hours",
})
print(kb_document)
```

## `delete()`

**Delete a knowledge-base document.** Deletes the document, its passages and its stored original. Assistants and the copilot stop answering from it at once.

```python
# client.kb_documents
def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedKbDocument
```

`client.kb_documents.delete()` · `await async_client.kb_documents.delete()` · `DELETE /kb/documents/{id}` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A kb document ID (`kbd_…`). |

### Returns

`DeletedKbDocument`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | A kb document ID (prefix `kbd_`). |
| `object` | `"kb_document"` | Always `kb_document`. |
| `deleted` | `true` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_kb_document = client.kb_documents.delete("kbd_7Hk2Lm9Qp")
print(deleted_kb_document)
```

## `list()`

**List knowledge-base documents.** Returns a page of `KbDocument` objects, newest first. Pass `next_cursor` as `starting_after` for the next page; the SDKs iterate every page for you.

```python
# client.kb_documents
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, status: _m.KbDocumentsListStatus | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.KbDocument]
```

`client.kb_documents.list()` · `await async_client.kb_documents.list()` · `GET /kb/documents` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `status` | `"pending" \| "processing" \| "ready" \| "error"` | no | Only documents in this status. |

### Returns

A page of results (`KbDocumentList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for kb_document in client.kb_documents.list():
    print(kb_document)
```

## `reingest()`

**Re-index a knowledge-base document.** Reads the document again — a URL is fetched again, a file is re-read from its stored original — and re-indexes it in the background (202). 409 when the original of an uploaded file is not stored: upload it again.

```python
# client.kb_documents
def reingest(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.KbDocument
```

`client.kb_documents.reingest()` · `await async_client.kb_documents.reingest()` · `POST /kb/documents/{id}/reingest` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_reingest/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A kb document ID (`kbd_…`). |

### Returns

`KbDocument`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The document's ID. |
| `object` | `"kb_document"` | Always `kb_document`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `title` | `string` | — |
| `kind` | `"pdf" \| "docx" \| "md" \| "txt" \| "csv" \| "xlsx" \| "html" \| "url"` | The format it was read as; `url` for a web page. |
| `source` | `string` | The uploaded file's name, or the URL. |
| `status` | `"pending" \| "processing" \| "ready" \| "error"` | pending → processing → ready (searchable) \| error. Poll the document, or follow `kb.document.*` events. |
| `error` | `string \| null` | Why ingestion failed (status error). |
| `bytes` | `integer` | — |
| `chunk_count` | `integer` | Searchable passages the document was split into. |
| `original_stored` | `boolean` | The original file is kept (encrypted): GET …/content downloads it and reingest re-reads it. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

kb_document = client.kb_documents.reingest("kbd_7Hk2Lm9Qp")
print(kb_document)
```

## `retrieve()`

**Retrieve a knowledge-base document.** Returns the `KbDocument` object. Answers `404` with the code `resource_missing` when nothing has this ID in this organisation and mode.

```python
# client.kb_documents
def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.KbDocument
```

`client.kb_documents.retrieve()` · `await async_client.kb_documents.retrieve()` · `GET /kb/documents/{id}` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A kb document ID (`kbd_…`). |

### Returns

`KbDocument`:

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | The document's ID. |
| `object` | `"kb_document"` | Always `kb_document`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `title` | `string` | — |
| `kind` | `"pdf" \| "docx" \| "md" \| "txt" \| "csv" \| "xlsx" \| "html" \| "url"` | The format it was read as; `url` for a web page. |
| `source` | `string` | The uploaded file's name, or the URL. |
| `status` | `"pending" \| "processing" \| "ready" \| "error"` | pending → processing → ready (searchable) \| error. Poll the document, or follow `kb.document.*` events. |
| `error` | `string \| null` | Why ingestion failed (status error). |
| `bytes` | `integer` | — |
| `chunk_count` | `integer` | Searchable passages the document was split into. |
| `original_stored` | `boolean` | The original file is kept (encrypted): GET …/content downloads it and reingest re-reads it. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

kb_document = client.kb_documents.retrieve("kbd_7Hk2Lm9Qp")
print(kb_document)
```

## `retrieve_content()`

**Download a document's original file.** The uploaded original, as it was uploaded (its own content type). 404 for URL documents and when the original is not stored (`original_stored: false`). Every download is audited.

```python
# client.kb_documents
def retrieve_content(self, id: str, *, more_voice_version: str | Unset = UNSET) -> File
```

`client.kb_documents.retrieve_content()` · `await async_client.kb_documents.retrieve_content()` · `GET /kb/documents/{id}/content` · [API reference](https://docs.morevoice.ai/api/operations/kb_documents_retrieve_content/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `str` | yes | A kb document ID (`kbd_…`). |

### Returns

Nothing, on success.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.kb_documents.retrieve_content("kbd_7Hk2Lm9Qp")
print(data)
```