v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB

Templates

Namespace Templates

Instantiate Namespace Template

Instantiate namespace template.

post/v1/templates/namespaces/{template_id}/instantiate

Path parameters

template_idstring required

Template ID

Request body

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

descriptionstring nullable

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.

Example request

{
  "namespace_name": "my_demo"
}

Response

Successful Response

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

namespace_namestring 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}.

template_idstring 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_'.

statusstring

Instantiation status. REQUIRED. 'cloning' means the namespace is being created and data is being copied. 'ready' means the namespace is fully functional and ready to use. 'failed' means the cloning process encountered an error. Poll GET /namespaces/{namespace_id} to check when status becomes 'ready'. All data is cloned including collections, vectors, retrievers, and taxonomies.

task_idstring nullable

Task ID for tracking the clone operation. Can be used to poll task status if needed. Format: UUID string.

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

Example response

{
  "created_at": "2024-10-31T12:00:00Z",
  "description": "Template instantiation started - cloning in progress",
  "namespace_id": "ns_abc123xyz",
  "namespace_name": "my_ecommerce_demo",
  "status": "cloning",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "template_id": "tmpl_ecommerce"
}