---
title: "Create volume template"
method: POST
path: "/volume_templates"
tags: ["volumeTemplates"]
---

# Create volume template

`POST /volume_templates`

Creates a new volume template for initializing volumes with pre-configured filesystem contents. Optionally returns a presigned URL for uploading the template archive.

## Query parameters

- `upload` boolean
- `version` string

## Request body

- VolumeTemplate — Volume template for creating pre-configured volumes
  - `metadata` Metadata, required — Owner fields for Persistence
    - `createdAt` string — The date and time when the resource was created
    - `updatedAt` string — The date and time when the resource was updated
    - `createdBy` string — The user or service account who created the resource
    - `updatedBy` string — The user or service account who updated the resource
    - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
    - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
    - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
    - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
    - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
    - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
  - `spec` VolumeTemplateSpec, required — Volume template specification
    - `defaultSize` integer — Default size of the volume in MB
    - `description` string — Description of the volume template
  - `state` VolumeTemplateState — Volume template state
    - `lastVersionUploadedAt` string — Timestamp of last version upload
    - `latestVersion` string — Current/latest S3 version ID
    - `status` 'created' | 'ready' | 'error' — Status of the volume template (created, ready, error)
    - `versionCount` integer — Total number of versions for this template
  - `versions` VolumeTemplateVersion[] — List of versions for this template
    - `bucket` string — S3 bucket name where this version is stored
    - `contentSize` integer — Size of the template content in bytes
    - `name` string — Name of the template version
    - `region` string — AWS region where this version is stored
    - `status` 'CREATED' | 'READY' | 'FAILED' — Status of the version (CREATED, READY, FAILED)
    - `templateName` string — Template name this version belongs to
    - `versionId` string — S3 version ID for this template version
    - `workspace` string — Workspace name

## Response `200`

successful operation

- VolumeTemplate — Volume template for creating pre-configured volumes
  - `metadata` Metadata, required — Owner fields for Persistence
    - `createdAt` string — The date and time when the resource was created
    - `updatedAt` string — The date and time when the resource was updated
    - `createdBy` string — The user or service account who created the resource
    - `updatedBy` string — The user or service account who updated the resource
    - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
    - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
    - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
    - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
    - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
    - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
    - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
  - `spec` VolumeTemplateSpec, required — Volume template specification
    - `defaultSize` integer — Default size of the volume in MB
    - `description` string — Description of the volume template
  - `state` VolumeTemplateState — Volume template state
    - `lastVersionUploadedAt` string — Timestamp of last version upload
    - `latestVersion` string — Current/latest S3 version ID
    - `status` 'created' | 'ready' | 'error' — Status of the volume template (created, ready, error)
    - `versionCount` integer — Total number of versions for this template
  - `versions` VolumeTemplateVersion[] — List of versions for this template
    - `bucket` string — S3 bucket name where this version is stored
    - `contentSize` integer — Size of the template content in bytes
    - `name` string — Name of the template version
    - `region` string — AWS region where this version is stored
    - `status` 'CREATED' | 'READY' | 'FAILED' — Status of the version (CREATED, READY, FAILED)
    - `templateName` string — Template name this version belongs to
    - `versionId` string — S3 version ID for this template version
    - `workspace` string — Workspace name

---

[API](https://skmtc.net/blaxel/apis/blaxel-control-plane.md) · [All operations](https://skmtc.net/blaxel/apis/blaxel-control-plane/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blaxel/blaxel-control-plane/versions/dfa264bc72ee/schema)