Skip to main content
POST
Create a sandbox from a Blueprint

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.

Path Parameters

id
string
required

The Blueprint id.

Body

application/json
siteName
string

Defaults to the Blueprint name.

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 expires a demo/idle-mode sandbox after a fixed lifetime from creation/launch; inactivity renews the deadline while it is actively used.

Available options:
fixed,
inactivity
workerCode
string

Optional worker selection where the account is permitted to choose one.

Response

The new Site and its queued Blueprint run.

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.

run
object
required

One execution of a Blueprint in create, apply, or bake mode. Poll this resource to follow asynchronous Blueprint work.