Create a sandbox (or restore one from a template)
Creates a sandbox. All fields are optional; sensible defaults are used (latest WordPress, PHP 8.3, standard preset, auto-selected worker).
By default creation is synchronous: the request waits (up to ~60s) until the sandbox
is ready and returns status: "ready" with the admin credentials and login URL. If
provisioning takes longer, the response comes back with status: "creating" and HTTP
202 — poll GET /api/app/sites/{id} until it becomes "ready". Pass background: true
to skip the wait and return immediately (also 202 while still "creating").
Passing templateId restores a saved Template instead of provisioning a blank sandbox
(fast snapshot restore, no reinstall) — free on every plan, subject to the normal
sandbox-count and storage limits. In that mode, only siteName, duration,
expirationMode, and background apply; every other field below is silently ignored
(the sandbox inherits the Template’s WordPress/PHP stack).
Authorizations
Personal API token, sent as Authorization: Bearer <SANDYWP_API_KEY>. Obtain one from the dashboard account menu (API keys), sandywp auth login, or POST /api/account/tokens. A missing or invalid token returns 401 auth_required. Scoped OAuth tokens are limited to the Imports family and GET /api/account/me; see the top-level conventions.
Headers
Selects which of the caller's workspaces to act in, for accounts belonging to more than one (legacy alias: X-SandyWP-Organization). Defaults to the caller's own personal workspace when omitted. Every id in this API (sandboxes, Templates, repositories) is scoped to a single workspace, so this header changes which set of resources is visible.
Body
All fields optional; see individual field descriptions for defaults.
Display name; the slug is derived from it. A blank/omitted name gets a random friendly name, never the caller's account email.
2 - 80latest resolves to the newest stable release. Pre-release entries (currently 7.1-beta3) are replaced by the next beta/RC as they ship, and always provision cold (never via the warm pool).
latest, 7.1-beta3, 7.0.2, 7.0, 6.9, 6.8, 6.7, 6.6 8.3, 8.2, 8.1 Pin the sandbox to a specific worker/region (e.g. eu1). Omit to auto-select.
^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}$standard — no debug settings at provision time. debug — provisions with WP_DEBUG (and related toggles) on; see debugOptions.
standard, debug Only takes effect when provisioningPreset is debug (silently ignored, and forced to all-false, when the preset is standard). Unlike PUT .../debug, an omitted field here defaults to true (matching the "debug" preset) rather than false.
The sandbox's lifespan, interpreted per expirationMode. With expirationMode: fixed: 1h, 1d, 1w (default), 2w, 1m, or permanent. With expirationMode: inactivity: 10m, 30m, 1h, or 1d (there is no inactivity-mode permanent — a 400 invalid_expiration rejects that combination). 2w, 1m, and permanent additionally require a paid plan (402 duration_requires_paid_plan / 402 permanent_requires_paid_plan).
10m, 30m, 1h, 1d, 1w, 2w, 1m, permanent fixed (default), or inactivity to restart the selected duration whenever the sandbox is actively used. A background tab does not count as use.
fixed, inactivity Install as a subdirectory WordPress multisite network. Forces cold provisioning (bypasses the warm pool) because the network domain is baked in at install time. Ignored when templateId is set.
wordpress.org plugin slugs to preinstall and activate. Invalid slugs are dropped rather than rejected. Ignored when templateId is set.
10wordpress.org theme slugs to preinstall and activate. Ignored when templateId is set.
5Create by restoring this Template instead of provisioning a blank sandbox. When set, only siteName, duration, expirationMode, and background apply — every other field on this object is ignored.
"tpl_xyz789"
Return immediately with status: "creating" instead of waiting (up to ~60s) for the sandbox to become ready.
Response
The sandbox is ready.
The owner-facing view of a sandbox. Strips internal provisioning details (container/DB names, password hash, warm-pool ids, routing) and keeps only what a caller needs to use and log into the sandbox.

