curl -X POST "http://localhost:8080/namespaces" \
-H "Content-Type: application/json" \
-d '{
"namespace_name": "my-documents",
"type": "text"
}'
curl -X POST "http://localhost:8080/namespaces" \
-H "Content-Type: application/json" \
-d '{
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}'
{
"status": "success",
"message": "Namespace 'my-documents' created successfully.",
"namespace_name": "my-documents",
"type": "text",
"vector_dimension": null
}
{
"status": "success",
"message": "Namespace 'my-embeddings' created successfully.",
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}
{
"status": "failure",
"message": "Bad Request: namespace_name must contain only alphanumeric characters, hyphens, and underscores."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is only allowed for vector namespaces."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is required and must be > 0 for vector namespaces."
}
{
"status": "failure",
"message": "Namespace 'my-documents' already exists."
}
{
"status": "failure",
"message": "Internal Server Error creating namespace."
}
Namespace Management
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.
POST
/
namespaces
curl -X POST "http://localhost:8080/namespaces" \
-H "Content-Type: application/json" \
-d '{
"namespace_name": "my-documents",
"type": "text"
}'
curl -X POST "http://localhost:8080/namespaces" \
-H "Content-Type: application/json" \
-d '{
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}'
{
"status": "success",
"message": "Namespace 'my-documents' created successfully.",
"namespace_name": "my-documents",
"type": "text",
"vector_dimension": null
}
{
"status": "success",
"message": "Namespace 'my-embeddings' created successfully.",
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}
{
"status": "failure",
"message": "Bad Request: namespace_name must contain only alphanumeric characters, hyphens, and underscores."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is only allowed for vector namespaces."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is required and must be > 0 for vector namespaces."
}
{
"status": "failure",
"message": "Namespace 'my-documents' already exists."
}
{
"status": "failure",
"message": "Internal Server Error creating namespace."
}
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
string
required
Must be
application/jsonBody
string
required
Unique name for the namespace. Alphanumeric characters, hyphens, and underscores only. You may also send this field as
name.string
required
Namespace type.
"text" for document storage (text is embedded via Ollama on upload). "vector" for precomputed embedding storage.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"
}'
curl -X POST "http://localhost:8080/namespaces" \
-H "Content-Type: application/json" \
-d '{
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}'
Response fields
string
Request outcome.
"success" when the namespace was created; "failure" on error.string
Human-readable result or error description.
string
Name of the namespace that was created. Present on successful creation.
string
Namespace type that was stored:
"text" or "vector". Present on successful creation. Cannot be changed after creation.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
}
{
"status": "success",
"message": "Namespace 'my-embeddings' created successfully.",
"namespace_name": "my-embeddings",
"type": "vector",
"vector_dimension": 768
}
{
"status": "failure",
"message": "Bad Request: namespace_name must contain only alphanumeric characters, hyphens, and underscores."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is only allowed for vector namespaces."
}
{
"status": "failure",
"message": "Bad Request: vector_dimension is required and must be > 0 for vector namespaces."
}
{
"status": "failure",
"message": "Namespace 'my-documents' already exists."
}
{
"status": "failure",
"message": "Internal Server Error creating namespace."
}
Next Steps
After creating a namespace, you can:- Upload documents for text namespaces
- Upload vectors for vector namespaces
- List all namespaces to view your created namespaces
- Search your data once data is uploaded
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
Was this page helpful?