Environments

An environment is a first-class child of a site — its own database and files, its own preview URL, and its own observability. Every site serves production from the site itself; staging and branch environments are isolated clones of production, mapped to branches by your branch routes. Most application-layer operations (deploys, exec, cache purge) are env-scoped, because a plugin can be active on staging but not production.

The environment object

Field	Type	Description
id	string	Stable identifier, e.g. env_01J8....
site_id	string	The owning site.
type	string	staging or branch. A site has at most one staging environment; branch environments are one per branch.
branch	string | null	The git branch this environment tracks (branch environments).
git_ref	string | null	The ref currently deployed.
subdomain	string	The environment’s preview hostname.
status	string	provisioning, running, suspending, suspended, deleting, deleted, or failed.
last_active	string | null	Last observed traffic — idle branch environments are candidates for suspension.
created_at	string	RFC 3339 timestamp.

Create & list environments

POST /v1/sites/{siteID}/environments

environments:write Create an environment, cloned from production. Provisioning is non-instant, so this returns a 202 Accepted with an async job — environment.clone for a staging environment, environment.create for a branch environment.

Parameter	Type	Required	Description
type	string	yes	staging or branch.
branch	string	when type=branch	Git branch to map to this environment, e.g. feature/checkout.
copy_uploads	boolean	no	Also copy the production uploads into the new environment.

cURL

Create a branch environment

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 7d2a...b9" \
  -H "Content-Type: application/json" \
  -d '{ "type": "branch", "branch": "feature/checkout", "copy_uploads": true }'

Go

Create a branch environment

job, err := client.Environments.Create(ctx, "site_01J7...", forge.EnvironmentCreateParams{
    Type:        forge.EnvTypeBranch,
    Branch:      "feature/checkout",
    CopyUploads: true,
})

mf CLI

Create a branch environment

mf envs create --site site_01J7... \
  --type branch --branch feature/checkout --copy-uploads

Response (202 Accepted)

{
  "data": {
    "id": "job_01J9...",
    "type": "environment.create",
    "status": "queued",
    "progress": 0,
    "created_at": "2026-06-24T14:20:41Z",
    "resource": { "type": "environment", "id": "env_01J8...", "site_id": "site_01J7...", "env_id": "env_01J8..." },
    "result": null,
    "error": null,
    "links": { "self": "/v1/jobs/job_01J9...", "stream": "/v1/jobs/job_01J9.../stream" }
  },
  "request_id": "req_01J9..."
}

GET /v1/sites/{siteID}/environments · GET · DELETE /v1/sites/{siteID}/environments/{envID}

• List (environments:read) every environment on a site, cursor-paginated.
• Retrieve (environments:read) one environment.
• Delete (environments:write) an environment; returns a 202 job (environment.destroy).

Lifecycle actions

POST /v1/sites/{siteID}/environments/{envID}/{action}

environments:write One endpoint drives the whole lifecycle — {action} is one of refresh, reset, push, suspend, or resume. Each returns a 202 Accepted with a job. See environment lifecycle for the conceptual walkthrough.

Action	Effect
refresh	Reseed database and files from production.
reset	Return the environment to a clean baseline.
push	Promote the environment’s content back to production.
suspend	Pause the environment; stops serving and frees resources.
resume	Bring a suspended environment back online.

Refresh a branch environment from production

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../refresh \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: c41e...30"

Push semantics

push moves content — not code — to production, and takes an optional body:

Parameter	Type	Required	Description
mode	string	no	What to push: files, db, or full. Defaults to files. Only push reads the body; other actions ignore it.

Two guardrails apply:

• On git-managed (bedrock) sites, only the staging environment may push — a branch environment returns 409, because branch code reaches production via merge and git deploy. On non-git (vanilla) sites any running environment may push.
• A verified production backup is taken before production is modified, so you can restore the pre-push state.

cURL

Push staging's database and files to production

curl -X POST https://api.managed.dev/v1/sites/site_01J7.../environments/env_01J8.../push \
  -H "Authorization: Bearer mfk_live_..." \
  -H "Idempotency-Key: 91be...4c" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "full" }'

Go

Push staging's database and files to production

job, err := client.Environments.Push(ctx, "site_01J7...", "env_01J8...", forge.PushModeFull)

mf CLI

Push staging's database and files to production

mf envs push env_01J8... --site site_01J7... --mode full

Renew

POST /v1/sites/{siteID}/environments/{envID}/renew

environments:write Re-issue the environment’s metrics token / lease. Unlike the lifecycle actions this is synchronous — it returns 200 with the renewal status, not a job.

Configuration

GET /v1/sites/{siteID}/environments/{envID}/config

environments:read The environment’s resolved configuration in three blocks, so you can see exactly where a value comes from:

Block	Meaning
inherited	The site-level baseline from site config.
override	This environment’s sparse override — only the fields set here.
effective	The merge the environment actually runs with.

Response (abridged)

{
  "data": {
    "inherited": { "performance": { "page_cache_ttl": 300 } },
    "override":  { "performance": { "page_cache_ttl": 0 } },   // caching off on this env
    "effective": { "performance": { "page_cache_ttl": 0 } }
  },
  "request_id": "req_01J9..."
}

Related env-scoped endpoints

Two shipped application-layer endpoints hang off the environment and are documented on their own pages:

• POST …/{envID}/exec — run WP-CLI in the environment as a streaming job (wp.cli:exec); see exec.
• POST …/{envID}/cache/purge — purge the page cache, all / by URL / by tag (cache:write); see cache.

Branch-to-environment routing is read at the site level: GET /v1/sites/{siteID}/branch-routes.

Next steps

Environment lifecycleThe conceptual walkthrough of refresh, reset, push, suspend, and resume.

DeploymentsBuild, deploy, promote, and roll back code on an environment.

Async jobsHow to track the 202 jobs these lifecycle actions return.