# mv.kbDocuments

> The kbDocuments methods of @morevoice/sdk: Knowledge-base documents assistants answer from.

Knowledge-base documents assistants answer from. These methods are on `mv.kbDocuments`, where `mv` is your client (see [the Node.js SDK](https://docs.morevoice.ai/sdk/node/#connect)). Each one returns the response object and throws 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.

```ts
mv.kbDocuments.create(body: KbDocumentsCreateData["body"], options?: RequestOptions): Promise<KbDocumentsCreateResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `body.file` | `object` | no | A file to upload. Or send the request as multipart/form-data with a `file` part. |
| `body.format` | `"md" \| "txt" \| "csv"` | no | With `text`: how to read it (default md). |
| `body.text` | `string` | no | Text to index as it is. |
| `body.title` | `string` | no | Default: the file's name, the page's title, or (text) "Document". |
| `body.url` | `string` | no | A public web page or file (http/https) to fetch and index. It is fetched again on reingest. |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options.headers["Idempotency-Key"]` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### 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

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const kbDocument = await mv.kbDocuments.create({
	text: "# Opening hours\nSunday–Thursday 08:00–18:00, Friday 08:00–13:00.",
	title: "Opening hours",
});
console.log(kbDocument);
```

## `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.

```ts
mv.kbDocuments.delete(id: KbDocumentsDeleteData["path"]["id"], options?: RequestOptions): Promise<KbDocumentsDeleteResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A kb document ID (`kbd_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options.headers["Idempotency-Key"]` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

`DeletedKbDocument`:

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

### Example

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const deletedKbDocument = await mv.kbDocuments.delete("kbd_7Hk2Lm9Qp");
console.log(deletedKbDocument);
```

## `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.

```ts
mv.kbDocuments.list(query?: NonNullable<KbDocumentsListData["query"]>, options?: RequestOptions): PagedList<KbDocumentsListResponse["data"][number], NonNullable<KbDocumentsListData["query"]>>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `query.limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `query.starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `query.ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `query.status` | `string` | no | Only documents in this status. |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

A [`PagedList`](https://docs.morevoice.ai/sdk/typescript/pagination/): `await` it for the first page, `for await` it for every item.

### Example

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

for await (const kbDocument of mv.kbDocuments.list()) {
	console.log(kbDocument);
}
```

## `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.

```ts
mv.kbDocuments.reingest(id: KbDocumentsReingestData["path"]["id"], options?: RequestOptions): Promise<KbDocumentsReingestResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A kb document ID (`kbd_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options.headers["Idempotency-Key"]` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### 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

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const kbDocument = await mv.kbDocuments.reingest("kbd_7Hk2Lm9Qp");
console.log(kbDocument);
```

## `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.

```ts
mv.kbDocuments.retrieve(id: KbDocumentsRetrieveData["path"]["id"], options?: RequestOptions): Promise<KbDocumentsRetrieveResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A kb document ID (`kbd_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### 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

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const kbDocument = await mv.kbDocuments.retrieve("kbd_7Hk2Lm9Qp");
console.log(kbDocument);
```

## `retrieveContent()`

**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.

```ts
mv.kbDocuments.retrieveContent(id: KbDocumentsRetrieveContentData["path"]["id"], options?: RequestOptions): Promise<KbDocumentsRetrieveContentResponse>
```

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

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | A kb document ID (`kbd_…`). |
| `options.headers["MoreVoice-Version"]` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `options` | `RequestOptions` | no | `idempotencyKey`, extra `headers` and an abort `signal`: see [retries and idempotency](https://docs.morevoice.ai/sdk/typescript/retries/). |

### Returns

Nothing, on success.

### Example

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const data = await mv.kbDocuments.retrieveContent("kbd_7Hk2Lm9Qp");
console.log(data);
```