Create a Template and start its initial Build
Creates a logical Template together with its initial Build. GMI creates
and starts the initial Build from the required build definition in the
same request.
Idempotency-Key is required and acts as the idempotency key because provider
creation can complete after an upstream timeout; a keyless retry would build a
second Template. Repeating the request with identical parameters replays the
same Template/Build (with Idempotency-Replayed: true); a different body under
the same key returns 400 Sandbox.IdempotentParameterMismatch; after the
Template is deleted the key answers 409 Sandbox.IdempotentKeyConsumed. Keys
are remembered for 24 hours. (X-Request-ID is trace-only and server-generated.)
resources supports two mutually exclusive forms:
- Preset:
{"type":"preset","product":"gmi.sandbox.x-large"}. Theproductvalue is the catalog SKU (seeGET /api/v2/products); the service resolves the active entry from the product catalog. Preset values are used as configured and are not constrained by custom resource limits. - Custom:
{"type":"custom","cpu_count":4,"memory_mb":8192, "disk_size_mb":32768,"architecture":"x86_64"}. All three numeric fields are required. Custom resources are limited to 16 vCPU, 65536 MiB memory, and 65536 MiB boot disk, and must also be representable by the selected IDC.
Authorizations
API Key or Access Token, always sent as Authorization: Bearer <token>. The gateway recognizes the token type automatically.
Headers
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.
1 - 64Body
Organization-scoped Template display name.
1 - 64^[A-Za-z0-9_-]+$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.
- Option 1
- Option 2
Human-readable Template description.
256IDC 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.
User-defined labels used for filtering.
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.