Skip to main content
POST
/
v1
/
namespaces
/
templates
/
{template_id}
/
instantiate
Instantiate Template
curl --request POST \
  --url https://api.mixpeek.com/v1/namespaces/templates/{template_id}/instantiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "namespace_name": "my_demo"
}'
{
  "created_at": "2024-10-31T12:00:00Z",
  "description": "Successfully instantiated e-commerce template",
  "namespace_id": "ns_abc123xyz",
  "namespace_name": "my_ecommerce_demo",
  "status": "ready",
  "template_id": "tmpl_ecommerce"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.

Headers

​
Authorization
string
required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Examples:

"Bearer sk_live_abc123def456"

"Bearer sk_test_xyz789"

Path Parameters

​
template_id
string
required

Body

application/json

Request to create a new namespace from a template.

Instantiation clones all data from the template's source namespace including:

  • Namespace configuration (feature extractors, indexes)
  • Qdrant vectors and payloads (pre-computed embeddings)
  • MongoDB metadata (collections, documents)

The process is fast (<5 seconds) because data is cloned, not reprocessed.

Use Cases: - First-time user onboarding with working examples - Creating demo environments for sales/trials - Spinning up test environments with known data - Providing industry-specific starting points

Requirements: - namespace_name: REQUIRED, must be unique within organization - description: OPTIONAL, defaults to template description if not provided

Validation: - Checks namespace name uniqueness before creation - Validates template exists and is active - Ensures source namespace is accessible

​
namespace_name
string
required

Name for the new namespace. REQUIRED. Must be unique within your organization. Used as identifier and display name. Format: 3-50 characters, alphanumeric with underscores/hyphens, lowercase recommended. Cannot match existing namespace names.

Required string length: 3 - 50
Examples:

"my_ecommerce_demo"

"test_media_lib"

"demo_docs_2024"

​
description
string | null

Optional description for the namespace. NOT REQUIRED. If not provided, uses the template's description. Useful for adding context about your specific use case. Format: 0-500 characters, plain text.

Maximum length: 500
Examples:

"Testing e-commerce search features for Q4 launch"

"Demo environment for customer presentation"

null

Response

Successful Response

Response after successful template instantiation.

Provides all information needed to start using the newly created namespace, including IDs for API calls and status information.

The namespace is immediately ready for use when status is 'ready'. All collections, documents, and feature stores are fully functional.

Use Cases: - Retrieve namespace_id for subsequent API calls - Verify instantiation completed successfully - Track which template was used for the namespace - Record creation timestamp for auditing

Fields: All fields are REQUIRED and populated by the server.

​
namespace_id
string
required

ID of the newly created namespace. REQUIRED. Use this ID in the X-Namespace header for all API calls to this namespace. Format: namespace ID starting with 'ns_'. Permanent identifier for the namespace.

Examples:

"ns_abc123xyz"

"ns_demo456def"

"ns_test789ghi"

​
namespace_name
string
required

Name of the newly created namespace. REQUIRED. Matches the namespace_name from the request. Human-readable identifier shown in UI. Can be used for namespace lookup via GET /namespaces/{name}.

Examples:

"my_ecommerce_demo"

"customer_demo_2024"

"test_media_lib"

​
template_id
string
required

ID of the template that was instantiated. REQUIRED. Reference to the source template used for creation. Useful for tracking which template produced this namespace. Format: template ID starting with 'tmpl_'.

Examples:

"tmpl_ecommerce"

"tmpl_media_library"

"tmpl_legal_docs"

​
status
string
default:ready

Instantiation status. REQUIRED. 'ready' means the namespace is fully functional and ready to use. All data has been cloned and indexes are built. You can immediately start querying collections and retrievers. Future: may support 'processing' or 'failed' states for async instantiation.

Examples:

"ready"

​
created_at
string<date-time>

Timestamp when namespace was created. REQUIRED. Auto-generated by server. Format: ISO 8601 datetime in UTC. Used for auditing and sorting namespaces by creation time.