Skip to main content
POST
Create a sandbox (or restore one from a template)

Authorizations

Authorization
string
header
required

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

X-SandyWP-Workspace
string

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

application/json

All fields optional; see individual field descriptions for defaults.

siteName
string

Display name; the slug is derived from it. A blank/omitted name gets a random friendly name, never the caller's account email.

Required string length: 2 - 80
wordpressVersion
enum<string>

latest 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).

Available options:
latest,
7.1-beta3,
7.0.2,
7.0,
6.9,
6.8,
6.7,
6.6
phpVersion
enum<string>
Available options:
8.3,
8.2,
8.1
workerCode
string

Pin the sandbox to a specific worker/region (e.g. eu1). Omit to auto-select.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,31}$
provisioningPreset
enum<string>

standard — no debug settings at provision time. debug — provisions with WP_DEBUG (and related toggles) on; see debugOptions.

Available options:
standard,
debug
debugOptions
object

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.

duration
enum<string>

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).

Available options:
10m,
30m,
1h,
1d,
1w,
2w,
1m,
permanent
expirationMode
enum<string>

fixed (default), or inactivity to restart the selected duration whenever the sandbox is actively used. A background tab does not count as use.

Available options:
fixed,
inactivity
multisite
boolean

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.

plugins
string[]

wordpress.org plugin slugs to preinstall and activate. Invalid slugs are dropped rather than rejected. Ignored when templateId is set.

Maximum array length: 10
Example:
themes
string[]

wordpress.org theme slugs to preinstall and activate. Ignored when templateId is set.

Maximum array length: 5
templateId
string

Create 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.

Example:

"tpl_xyz789"

background
boolean

Return immediately with status: "creating" instead of waiting (up to ~60s) for the sandbox to become ready.

Response

The sandbox is ready.

site
object
required

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.