Add a knowledge-base document

POST

/kb/documents

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);

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)

curl -X POST https://api.morevoice.ai/v1/kb/documents \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "# Opening hours\nSunday–Thursday 08:00–18:00, Friday 08:00–13:00.",
  "title": "Opening hours"
}'

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.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

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.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body^required

A document to add: exactly one of file, url and text. It is indexed in the background (202): poll it until status is ready.

object

file

A file to upload. Or send the request as multipart/form-data with a file part.

object

content_base64

required

The file, base64-encoded (≤ 25 MB decoded).

string

>= 1 characters <= 34952538 characters

filename

required

Its name; the extension picks the format (.pdf, .docx, .xlsx, .csv, .md, .txt, .html).

string

>= 1 characters <= 200 characters

format

With text: how to read it (default md).

string

Allowed values: md txt csv

text

Text to index as it is.

string

>= 1 characters <= 2000000 characters

title

Default: the file’s name, the page’s title, or (text) “Document”.

string

>= 1 characters <= 200 characters

url

A public web page or file (http/https) to fetch and index. It is fetched again on reingest.

string format: uri

<= 2000 characters

Example

{
  "text": "# Opening hours\nSunday–Thursday 08:00–18:00, Friday 08:00–13:00.",
  "title": "Opening hours"
}

Responses

202

Accepted: the document is indexed in the background.

application/json

A document in your knowledge base: assistants and the agent copilot answer from it.

object

bytes

required

integer

>= -9007199254740991 <= 9007199254740991

chunk_count

required

Searchable passages the document was split into.

integer

>= -9007199254740991 <= 9007199254740991

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

error

required

Why ingestion failed (status error).

string | null

required

The document’s ID.

string

/^kbd_[0-9A-Za-z]+$/

kind

required

The format it was read as; url for a web page.

string

Allowed values: pdf docx md txt csv xlsx html url

livemode

required

true in live mode, false in test mode.

boolean

object

required

string

Allowed value: kb_document

original_stored

required

The original file is kept (encrypted): GET …/content downloads it and reingest re-reads it.

boolean

source

required

The uploaded file’s name, or the URL.

string

status

required

Pending → processing → ready (searchable) | error. Poll the document, or follow kb.document.* events.

string

Allowed values: pending processing ready error

title

required

string

updated

required

An ISO-8601 timestamp in UTC.

string format: date-time

Example

{
  "bytes": 184320,
  "chunk_count": 42,
  "created": "2026-11-03T09:14:22.000Z",
  "error": null,
  "id": "kbd_6Nq0Sv3Xa5Cf8Hk1Mp4Rt7",
  "kind": "pdf",
  "livemode": true,
  "object": "kb_document",
  "original_stored": true,
  "source": "price-list-2026.pdf",
  "status": "ready",
  "title": "Price list 2026",
  "updated": "2026-11-03T09:14:31.000Z"
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Add a knowledge-base document

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Example

Responses

202

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required