Upload Documents

documents.upload

Uploads one or more documents to a text namespace. Each document is embedded with the configured embedding provider and stored for semantic search. The upload runs asynchronously — poll client.documents.upload_job_status with the returned job_id.

client.documents.upload(
    namespace_name: str,
    *,
    documents: list[dict],
) -> dict[str, Any]

The * means documents is keyword-only. Extra fields on each document (for example team, source) are stored as metadata for search filters (#team:ai in the query).

API: POST /namespaces/{namespace_name}/documents — see Upload documents

Parameters

string

required

Target text namespace.

array

required

Non-empty array of document objects.

string

required

Item id, unique within this namespace.

string

required

Document text to embed and store.

any

Optional additional keys on each document are saved as metadata (for example "team": "ai").

Examples

from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    try:
        resp = client.documents.upload(
            "my-documents",
            documents=[
                {
                    "id": "doc-1",
                    "text": "Moorcheh on-prem retrieval test",
                    "team": "ai",
                },
            ],
        )
        job_id = resp["job_id"]
    except MoorchehApiError as e:
        if e.is_item_limit_exceeded:
            print(e.body)  # items, max_items, requested_new
        else:
            raise

Poll with documents.upload_job_status.

Returns

string

"success" when the upload job was started.

string

Human-readable result description.

string

Id of the async upload job. Poll documents.upload_job_status with this value.

string

Namespace the documents are being uploaded to.

number

Number of documents accepted into the upload job.

number

Current total item count on the instance. Present on 409 item limit errors in MoorchehApiError.body.

number

Global item cap for this instance. Present on 409 item limit errors.

number

Number of new item ids in the request that would exceed the cap. Present on 409 item limit errors.

Example return value

{
  "status": "success",
  "message": "Documents upload started. Poll job status for progress.",
  "job_id": "job-a0e3d54b9d0d4616949474697308a39c",
  "namespace_name": "my-documents",
  "total": 1,
}

Error Handling

Non-2xx responses raise MoorchehApiError. Use e.is_item_limit_exceeded for 409 quota errors.

from moorcheh import MoorchehClient, MoorchehApiError

try:
    with MoorchehClient() as client:
        client.documents.upload("my-documents", documents=[...])
except MoorchehApiError as e:
    print(e.status_code, e.body)

Status	Cause
400	Empty `documents`, missing `id`/`text`, or wrong namespace type
404	Namespace not found
409	Global item limit would be exceeded (job not started)

At most 100,000 items total across all namespaces
409 is returned before the job starts if new ids would exceed the cap
Re-uploading an existing id in the same namespace updates the item and does not consume extra quota

Getting Started

System

Namespace Management

Search

AI Generation

Data Operations

File storage

Items

documents.upload

Parameters

Examples

Returns

Error Handling

​documents.upload

​Parameters

​Examples

​Returns

​Error Handling

​Related Operations

documents.upload

Parameters

Examples

Returns

Error Handling

Related Operations