---
title: "Instantiate Scaffold Template"
method: POST
path: "/v1/templates/scaffolds/{template_id}/instantiate"
tags: ["Scaffold Templates"]
---

# Instantiate Scaffold Template

`POST /v1/templates/scaffolds/{template_id}/instantiate`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/templates/scaffolds/{template_id}/instantiate`
- Auth: HTTP bearer

Create complete infrastructure from scaffold template.

Creates all resources atomically:
1. **Namespace** with configured feature extractors
2. **Bucket** with schema for your data structure
3. **Collection** linked to bucket with feature config
4. **Retriever** with search pipeline stages

All resources are empty, ready for data upload.

**Next Steps:**
1. Upload data: `POST /v1/buckets/{bucket_id}/objects`
2. Process batch: `POST /v1/collections/{collection_id}/batches`
3. Search: `POST /v1/retrievers/{retriever_id}/retrieve`

**Example Request:**
```json
{
    "namespace_name": "my_video_app",
    "namespace_description": "Video search application"
}
```

## Path parameters

- `template_id` string, required: Scaffold template ID

## Request body

- InstantiateScaffoldRequest: Request to instantiate a scaffold template. Only namespace_name is required. Other names use scaffold defaults. Options: include_sample_data: If true, clone from demo namespace with sample data. If false (default), create empty resources. Example: # Empty scaffold {"namespace_name": "my_app"} # With sample data {"namespace_name": "my_app", "include_sample_data": true}
  - `namespace_name` string, required: Name for the new namespace (required, must be unique)
  - `namespace_description` string, nullable: Optional description for the namespace
  - `bucket_name` string, nullable: Override default bucket name from scaffold
  - `collection_name` string, nullable: Override default collection name from scaffold
  - `retriever_name` string, nullable: Override default retriever name from scaffold
  - `include_sample_data` boolean: If true, include sample data from demo namespace. If false, create empty resources.

## Response `200`

Successful Response

- InstantiatedScaffoldResponse: Response after successful scaffold instantiation. Contains IDs and names of all four created resources. Use these IDs for subsequent operations: - Upload data: POST /v1/buckets/{bucket_id}/objects - Process: POST /v1/collections/{collection_id}/batches - Search: POST /v1/retrievers/{retriever_id}/retrieve
  - `namespace_id` string, required: Created namespace ID (ns_xxx)
  - `namespace_name` string, required: Created namespace name
  - `bucket_id` string, required: Created bucket ID (bkt_xxx)
  - `bucket_name` string, required: Created bucket name
  - `collection_id` string, required: Created collection ID (col_xxx)
  - `collection_name` string, required: Created collection name
  - `retriever_id` string, required: Created retriever ID (ret_xxx)
  - `retriever_name` string, required: Created retriever name
  - `template_id` string, required: Scaffold template ID used
  - `status` string: Status: 'created' for a synchronous (empty) instantiation, 'cloning' when sample data is cloning in the background
  - `task_id` string, nullable: Background clone task id when status='cloning' — poll the task, or GET the namespace and read clone_status, to track sample-data progress. Null for synchronous (empty) instantiation.
  - `created_at` string, date-time: UTC timestamp of creation

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-10-04** `38e0822db900`: 1 breaking, 1 info
  - removed the success response with the status `201`
  - added the success response with the status `200`
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/templates/scaffolds/:template_id/instantiate/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)