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

# Create Namespace

> Create a new namespace using the Python client

## namespaces.create

Creates a new namespace for storing text documents or precomputed vector embeddings on your on-prem Moorcheh instance.

```python theme={null}
client.namespaces.create(
    namespace_name: str,
    *,
    type: Literal["text", "vector"],
    vector_dimension: int | None = None,
) -> dict[str, Any]
```

<Note>
  The `*` in the signature means everything after it is **keyword-only**. You must pass `type` and `vector_dimension` by name — for example `type="text"` — not as extra positional arguments.
</Note>

**API:** `POST /namespaces` — see [Create namespace](/on-prem/api-references/namespaces/create)

### Parameters

<ParamField body="namespace_name" type="str" required>
  A unique name for the namespace. Alphanumeric characters, hyphens, and underscores only.
</ParamField>

<ParamField body="type" type="str" required>
  The type of namespace: `"text"` or `"vector"`.
</ParamField>

<ParamField body="vector_dimension" type="Optional[int]">
  The dimension of vectors. Required when `type` is `"vector"`. Must be greater than 0. Do not pass for text namespaces.
</ParamField>

**Returns:** `dict[str, Any]` — confirmation with `status`, `message`, `namespace_name`, `type`, and `vector_dimension`.

**Raises:** `MoorchehApiError` — HTTP **400** for invalid input, **409** when the namespace already exists.

### Examples

```python Create Text Namespace theme={null}
from moorcheh import MoorchehClient

with MoorchehClient("http://localhost:8080") as client:
    # Moorcheh embeds documents on upload (Ollama, OpenAI, or Cohere)
    result = client.namespaces.create(
        "my-faq-documents",
        type="text",
    )
    print(f"Created namespace: {result}")
```

```python Create Vector Namespace theme={null}
from moorcheh import MoorchehClient

with MoorchehClient("http://localhost:8080") as client:
    # You supply precomputed vectors; length must match vector_dimension
    result = client.namespaces.create(
        "my-image-embeddings",
        type="vector",
        vector_dimension=768,
    )
    print(f"Created namespace: {result}")
```

### Error Handling

On-prem uses a single exception type. Check `e.status_code` and `e.body` for details.

```python Error Handling Example theme={null}
from moorcheh import MoorchehClient, MoorchehApiError

with MoorchehClient("http://localhost:8080") as client:
    try:
        result = client.namespaces.create("my-documents", type="text")
        print(f"Created namespace: {result}")
    except MoorchehApiError as e:
        if e.status_code == 409:
            print("Namespace already exists")
        elif e.status_code == 400:
            print(f"Invalid input: {e.body}")
        else:
            raise
```

| Status | Cause                                                                                              |
| ------ | -------------------------------------------------------------------------------------------------- |
| 400    | Invalid name, missing `vector_dimension` for vector type, or `vector_dimension` sent for text type |
| 409    | Namespace already exists                                                                           |

```python Example return value (text) theme={null}
{
  "status": "success",
  "message": "Namespace 'my-documents' created successfully.",
  "namespace_name": "my-documents",
  "type": "text",
  "vector_dimension": None,
}
```

## Namespace Types

| Feature          | Text Namespaces                                                             | Vector Namespaces                           |
| :--------------- | :-------------------------------------------------------------------------- | :------------------------------------------ |
| **Primary use**  | Storing and searching text documents                                        | Storing pre-computed vector embeddings      |
| **Embeddings**   | Generated on upload by your configured provider (Ollama, OpenAI, or Cohere) | Provided by you                             |
| **Requirements** | Embedding provider configured via `moorcheh configure`                      | Must specify `vector_dimension` at creation |
| **Search**       | Text query → embedded → similarity search                                   | Vector query → similarity search            |
| **Ideal for**    | FAQs, documentation, articles                                               | Custom ML models, image embeddings          |

## Best Practices

* Use descriptive namespace names that indicate their purpose
* Separate different content types into different namespaces
* Plan your data layout before creating namespaces — `type` cannot be changed after creation
* Prefer text namespaces for most workflows; use vector namespaces only when you supply your own embeddings
* Match `vector_dimension` to your embedding model (for example `768` or `1536`)

## Related Operations

* [List Namespaces](/on-prem/python-client/namespaces/list) — view all namespaces
* [Delete Namespace](/on-prem/python-client/namespaces/delete) — remove a namespace
* [API: Create namespace](/on-prem/api-references/namespaces/create)
* [CLI: moorcheh namespace-create](/on-prem/cli/namespaces/create)