Skip to main content

​
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

​
namespace_name
string
required
Target text namespace.
​
documents
array
required
Non-empty array of document objects.
​
documents[].id
string
required
Item id, unique within this namespace.
​
documents[].text
string
required
Document text to embed and store.
​
documents[].{metadata}
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

​
status
string
"success" when the upload job was started.
​
message
string
Human-readable result description.
​
job_id
string
Id of the async upload job. Poll documents.upload_job_status with this value.
​
namespace_name
string
Namespace the documents are being uploaded to.
​
total
number
Number of documents accepted into the upload job.
​
items
number
Current total item count on the instance. Present on 409 item limit errors in MoorchehApiError.body.
​
max_items
number
Global item cap for this instance. Present on 409 item limit errors.
​
requested_new
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)
StatusCause
400Empty documents, missing id/text, or wrong namespace type
404Namespace not found
409Global 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