> ## 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 to organize and store your data. Namespaces can be either text-based for document storage or vector-based for embedding storage.

## Overview

Create a new namespace to organize and store your data. Namespaces provide isolated environments for your documents or vectors, ensuring data separation and organized data management.

<Note>
  Namespace names must be unique on this Moorcheh instance and can only contain alphanumeric characters, hyphens, and underscores.
</Note>

<Note>
  On-prem does not use API keys. Start the server with `moorcheh up` before calling this endpoint.
</Note>

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Body

<ParamField body="namespace_name" type="string" required>
  Unique name for the namespace. Alphanumeric characters, hyphens, and underscores only. You may also send this field as `name`.
</ParamField>

<ParamField body="type" type="string" required>
  Namespace type. `"text"` for document storage (text is embedded via Ollama on upload). `"vector"` for precomputed embedding storage.
</ParamField>

<ParamField body="vector_dimension" type="number">
  Required when `type` is `"vector"`. Must be greater than 0. Every vector uploaded to this namespace must have exactly this many dimensions (for example `768` for many open models, or `1536` for OpenAI `text-embedding-3-small`). Must not be sent for text namespaces.
</ParamField>

<RequestExample>
  ```bash Text Namespace theme={null}
  curl -X POST "http://localhost:8080/namespaces" \
    -H "Content-Type: application/json" \
    -d '{
      "namespace_name": "my-documents",
      "type": "text"
    }'
  ```

  ```bash Vector Namespace theme={null}
  curl -X POST "http://localhost:8080/namespaces" \
    -H "Content-Type: application/json" \
    -d '{
      "namespace_name": "my-embeddings",
      "type": "vector",
      "vector_dimension": 768
    }'
  ```
</RequestExample>

## Response fields

<ResponseField name="status" type="string">
  Request outcome. `"success"` when the namespace was created; `"failure"` on error.
</ResponseField>

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

<ResponseField name="namespace_name" type="string">
  Name of the namespace that was created. Present on successful creation.
</ResponseField>

<ResponseField name="type" type="string">
  Namespace type that was stored: `"text"` or `"vector"`. Present on successful creation. Cannot be changed after creation.
</ResponseField>

<ResponseField name="vector_dimension" type="number | null">
  Fixed vector length for vector namespaces; `null` for text namespaces. Present on successful creation. All future vector uploads must match this dimension.
</ResponseField>

<ResponseExample>
  ```json 200 - Text Namespace theme={null}
  {
    "status": "success",
    "message": "Namespace 'my-documents' created successfully.",
    "namespace_name": "my-documents",
    "type": "text",
    "vector_dimension": null
  }
  ```

  ```json 200 - Vector Namespace theme={null}
  {
    "status": "success",
    "message": "Namespace 'my-embeddings' created successfully.",
    "namespace_name": "my-embeddings",
    "type": "vector",
    "vector_dimension": 768
  }
  ```

  ```json 400 - Bad Request (invalid name) theme={null}
  {
    "status": "failure",
    "message": "Bad Request: namespace_name must contain only alphanumeric characters, hyphens, and underscores."
  }
  ```

  ```json 400 - Bad Request (vector dimension on text namespace) theme={null}
  {
    "status": "failure",
    "message": "Bad Request: vector_dimension is only allowed for vector namespaces."
  }
  ```

  ```json 400 - Bad Request (missing vector dimension) theme={null}
  {
    "status": "failure",
    "message": "Bad Request: vector_dimension is required and must be > 0 for vector namespaces."
  }
  ```

  ```json 409 - Conflict theme={null}
  {
    "status": "failure",
    "message": "Namespace 'my-documents' already exists."
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "status": "failure",
    "message": "Internal Server Error creating namespace."
  }
  ```
</ResponseExample>

## Next Steps

After creating a namespace, you can:

* [Upload documents](/on-prem/api-references/data/upload-documents) for text namespaces
* [Upload vectors](/on-prem/api-references/data/upload-vectors) for vector namespaces
* [List all namespaces](/on-prem/api-references/namespaces/list) to view your created namespaces
* [Search your data](/on-prem/api-references/search/query) once data is uploaded

## Important Notes

<Warning>
  * Namespace type cannot be changed after creation
  * Vector dimension must be specified for vector namespaces and cannot be modified later
  * Namespace names must be unique on this Moorcheh instance
  * On-prem has no cloud tier namespace limits — only the global **100,000 item** storage cap applies to uploaded data
</Warning>