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

# Getting Started

> End-to-end Python client workflow: health, namespace, upload, poll, search

## Prerequisites

```bash theme={null}
pip install moorcheh-client
moorcheh up
```

Confirm the server is running:

```python theme={null}
from moorcheh import MoorchehClient

with MoorchehClient("http://localhost:8080") as client:
    health = client.health()
    assert health["status"] == "ok"
```

See [health](/on-prem/python-client/health) for quota fields.

## Full example — text namespace

```python theme={null}
import time
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    # 1. Check quota
    health = client.health()
    print(f"Items: {health['items']} / {health['max_items']}")

    # 2. Create a text namespace
    try:
        client.namespaces.create("docs", type="text")
    except MoorchehApiError as e:
        if e.status_code != 409:  # 409 = namespace already exists
            raise

    # 3. Upload documents (async job)
    resp = client.documents.upload("docs", documents=[
        {"id": "doc-1", "text": "Hello Moorcheh", "team": "ai"},
    ])

    # 4. Poll until upload completes
    job_id = resp["job_id"]
    while True:
        job = client.documents.upload_job_status("docs", job_id)
        if job["status"] == "completed":
            if job["failed"]:
                print("Upload errors:", job.get("last_error"))
            break
        time.sleep(0.5)

    # 5. Search (use #team:ai in query for metadata filter)
    hits = client.similarity_search.query(
        namespaces=["docs"],
        query="hello moorcheh #team:ai",
        top_k=5,
    )

    for r in hits["results"]:
        print(r["id"], r["score"], r["label"], r.get("text"))
```

## Vector namespace (optional)

```python theme={null}
with MoorchehClient("http://localhost:8080") as client:
    client.namespaces.create("embeddings", type="vector", vector_dimension=768)

    resp = client.vectors.upload("embeddings", vectors=[
        {"id": "vec-1", "vector": [0.1] * 768, "source": "demo"},
    ])

    # Poll upload job, then search with a vector query
    hits = client.similarity_search.query(
        namespaces=["embeddings"],
        query=[0.1] * 768,
        top_k=5,
    )
```

## CLI equivalent

```bash theme={null}
moorcheh status
moorcheh namespace-create --name docs --type text
moorcheh upload-documents --namespace-name docs --documents-file docs.json
moorcheh upload-job-status --namespace-name docs --job-id <job_id>
moorcheh search --query "hello moorcheh" --namespaces docs --top-k 5
```

## Method reference

| Step | Python (resource style) | Docs |
| - | - | - |
| Health / quota | `client.health()` | [health](/on-prem/python-client/health) |
| Create namespace | `client.namespaces.create(...)` | [create](/on-prem/python-client/namespaces/create) |
| Upload documents | `client.documents.upload(...)` | [upload](/on-prem/python-client/data/upload-documents) |
| Poll upload | `client.documents.upload_job_status(...)` | [upload job status](/on-prem/python-client/data/upload-job-status) |
| Upload file | `client.files.upload(...)` | [upload files](/on-prem/python-client/files/upload-files) |
| Poll file job | `client.files.job_status(...)` | [file job status](/on-prem/python-client/files/file-job-status) |
| Search | `client.similarity_search.query(...)` | [search](/on-prem/python-client/search/query) |

## Tips

<Warning>
  * Text upload and text search require a configured embedding provider (`moorcheh configure`)
  * Global item cap is **100,000** across all namespaces — check `health()` or handle **409** on upload
  * Document upload, file upload, and namespace delete are **async** — poll the job until `status` is `"completed"`
  * Item ids are unique **per namespace**, not globally
</Warning>

## Next steps

* [Python client overview](/on-prem/python-client/introduction) — all resources and error handling
* [Quickstart](/on-prem/quickstart) — CLI walkthrough
* [API reference](/on-prem/api-references/health) — full HTTP API docs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.