Skip to main content
POST
/
namespaces
curl -X POST "http://localhost:8080/namespaces" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "my-documents",
    "type": "text"
  }'

{
  "status": "success",
  "message": "Namespace 'my-documents' created successfully.",
  "namespace_name": "my-documents",
  "type": "text",
  "vector_dimension": null
}

​
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.
Namespace names must be unique on this Moorcheh instance and can only contain alphanumeric characters, hyphens, and underscores.
On-prem does not use API keys. Start the server with moorcheh up before calling this endpoint.

​
Headers

​
Content-Type
string
required
Must be application/json

​
Body

​
namespace_name
string
required
Unique name for the namespace. Alphanumeric characters, hyphens, and underscores only. You may also send this field as name.
​
type
string
required
Namespace type. "text" for document storage (text is embedded via Ollama on upload). "vector" for precomputed embedding storage.
​
vector_dimension
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.
curl -X POST "http://localhost:8080/namespaces" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace_name": "my-documents",
    "type": "text"
  }'

​
Response fields

​
status
string
Request outcome. "success" when the namespace was created; "failure" on error.
​
message
string
Human-readable result or error description.
​
namespace_name
string
Name of the namespace that was created. Present on successful creation.
​
type
string
Namespace type that was stored: "text" or "vector". Present on successful creation. Cannot be changed after creation.
​
vector_dimension
number | null
Fixed vector length for vector namespaces; null for text namespaces. Present on successful creation. All future vector uploads must match this dimension.
{
  "status": "success",
  "message": "Namespace 'my-documents' created successfully.",
  "namespace_name": "my-documents",
  "type": "text",
  "vector_dimension": null
}

​
Next Steps

After creating a namespace, you can:

​
Important Notes

  • 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