> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# moorcheh upload-documents

> Upload text documents to a text namespace.

## Overview

Uploads documents from a JSON file to a **text** namespace. Embeddings are computed via Ollama. Returns an async `job_id` — poll with [moorcheh upload-job-status](/on-prem/cli/data/upload-job-status).

## Synopsis

```bash theme={null}
moorcheh upload-documents --namespace-name NAME --documents-file PATH [--base-url URL]
```

## Options

| Flag               | Required | Description                                |
| ------------------ | -------- | ------------------------------------------ |
| `--namespace-name` | Yes      | Target text namespace                      |
| `--documents-file` | Yes      | Path to JSON file with a `documents` array |
| `--base-url`       | No       | Default `http://localhost:8080`            |

## Documents file format

`docs.json`:

```json theme={null}
{
  "documents": [
    {
      "id": "doc-1",
      "text": "Moorcheh on-prem retrieval test",
      "team": "ai"
    }
  ]
}
```

Extra keys on each document (for example `team`) are stored as metadata.

## Examples

```bash theme={null}
moorcheh upload-documents --namespace-name my-documents --documents-file docs.json

moorcheh upload-job-status --namespace-name my-documents --job-id <job_id>
```

## Output

Prints JSON from `POST /namespaces/{namespace_name}/documents`:

<ResponseField name="status" type="string">
  `"success"` when the upload job was started; `"failure"` on error.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable result or error description.
</ResponseField>

<ResponseField name="job_id" type="string">
  Async upload job id.
</ResponseField>

<ResponseField name="namespace_name" type="string">
  Target namespace.
</ResponseField>

<ResponseField name="total" type="number">
  Number of documents accepted into the job.
</ResponseField>

<ResponseField name="items" type="number">
  Current item count. Present on **409** item limit errors.
</ResponseField>

<ResponseField name="max_items" type="number">
  Global item cap. Present on **409** errors.
</ResponseField>

<ResponseField name="requested_new" type="number">
  New ids that would exceed the cap. Present on **409** errors.
</ResponseField>

```json Example output theme={null}
{
  "status": "success",
  "message": "Documents upload started. Poll job status for progress.",
  "job_id": "job-9889a2ea08034064adb584d0afdf45b1",
  "namespace_name": "my-documents",
  "total": 1
}
```

## Exit codes

| Code | Meaning                                                                   |
| ---- | ------------------------------------------------------------------------- |
| `0`  | Upload job started                                                        |
| `1`  | API error (400, 404, 409, etc.) — error JSON on stdout, message on stderr |

## Related

* [CLI: upload-job-status](/on-prem/cli/data/upload-job-status)
* [API: Upload documents](/on-prem/api-references/data/upload-documents)
* [Python: documents.upload()](/on-prem/python-client/data/upload-documents)