Create a sandbox
Creates a sandbox from a template_id.
Compute resources (CPU / memory / disk / architecture) are inherited from the snapshot of the selected Template Build. They are fixed when the Template is built and cannot be overridden at creation time.
Idempotency: pass an explicit Idempotency-Key request header as the idempotency key (unrelated to the tracing header X-Request-ID, which is always generated server-side; a client-supplied value is ignored). Resubmitting the same key with identical parameters returns the sandbox created by the first request (with its current access data) plus an Idempotency-Replayed: true response header. The same key with different parameters returns 400 Sandbox.IdempotentParameterMismatch. If the creation under that key has deterministically failed, or the sandbox it created has been deleted, the request returns 409 Sandbox.IdempotentKeyConsumed (retryable failures are automatically re-attempted when the same key is retried). The deduplication window is 24 hours; after it expires the same key is treated as a new request. Without the header, no deduplication is performed.
Backends that create asynchronously return as soon as the request is accepted: the instance starts in provisioning and transitions to running once ready. The detail endpoint is queryable during this period (see GET /sandboxes/).
The sandbox_access_token stays valid for the entire lifetime of the sandbox.
Authorizations
API Key or Access Token, always sent as Authorization: Bearer <token>. The gateway recognizes the token type automatically.
Headers
Optional caller-generated idempotency key (a UUID is recommended). Matched byte-for-byte: 1-64 printable ASCII characters, no whitespace. Absent means no deduplication. 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
Template identifier or name. A snapshot-as-template snapshotID is also valid here.
Target data center name, e.g. us-central1-c. Optional: when omitted, the organization's configured default data center is used (maintained by the platform administrator); if the organization has no default configured, the request returns 400. Note that Templates are bound to a data center: the effective data center (whether explicit or default) must match the one that owns the Template referenced by template_id, otherwise the request is treated as template-not-found.
Time-to-live in seconds. When omitted or 0 or less, 300 seconds is used.
Customer-defined key/value pairs; the platform does not interpret them. The list endpoint can filter by them.