Skip to main content
POST
Create a Template and start its initial Build

Authorizations

Authorization
string
header
required

API Key or Access Token, always sent as Authorization: Bearer <token>. The gateway recognizes the token type automatically.

Headers

Idempotency-Key
string
required

Caller-generated key that makes the mutation safe to retry (a UUID is recommended). Matched byte-for-byte: 1-64 printable ASCII characters, no whitespace. The same key with a different request body returns 400 Sandbox.IdempotentParameterMismatch. Echoed on responses; replays add Idempotency-Replayed: true. Keys are remembered for 24 hours.

Required string length: 1 - 64

Body

application/json
name
string
required

Organization-scoped Template display name.

Required string length: 1 - 64
Pattern: ^[A-Za-z0-9_-]+$
resources
object
required

Resource values may be selected by catalog product SKU or supplied as a custom configuration. Active presets use operator-managed IDC product values without custom-resource limit validation. Only custom values must pass the 16 vCPU / 64 GiB memory / 64 GiB boot disk limits and the selected IDC's representability checks.

description
string

Human-readable Template description.

Maximum string length: 256
idc_name
string

IDC that permanently owns the Template. Optional: omitted, empty, and whitespace-only values are equivalent — the organization's configured default data center is used (maintained by the platform administrator; the same setting used by sandbox creation). If the organization has no default configured, the request returns 400.

labels
object

User-defined labels used for filtering.

build
object

Initial Build definition created and started with the Template (combined flow, every IDC supports it). Omitting build selects the split flow: the Template and a waiting initial Build are created without starting anything, and the Build is started later via POST /templates/{template_id}/builds/{id}. The split flow is not supported in every IDC; unsupported IDCs reject it with 422.

Response

The Template record is created and immediately addressable: GET /templates/{id} works right away, and a failed initial Build leaves a rebuildable Template rather than erasing it. Build readiness is reported by status, not by the status code.

request_id
string
required

HTTP request correlation identifier.

data
object
required