Manage Staging Environments via API

The staging environment of a hosted site can be driven over the API, so you can wire a pull or a push into a deploy script, a CI job or an AI agent workflow instead of clicking through the dashboard.

This is the staging environment of a site hosted on InstaWP. If you are linking a production and a staging site that live on other hosts, using the InstaWP Connect plugin, you want Link Two Sites Programmatically instead.

📘 Full API documentation: apidocs.instawp.com is the complete InstaWP API reference, with every endpoint, its parameters and example responses. Use it alongside this page for authentication, error formats, rate limits and everything the API can do beyond staging.

Let's get started 🚀

Before you start

• Your site needs to be on the Pro, Turbo or Elite plan. See Staging Environment for Hosted Sites for the full eligibility list.
• You need an account API token. See Create an API Token.
• You need the site ID of your production site. See Find a Site's Slug, or list your sites over the API.

The endpoints

Base URL: https://app.instawp.io/api

Method	Endpoint	What it does
POST	/v2/sites/{site}/staging	Create the staging environment
POST	/v2/sites/{site}/staging/reset	Pull production down to staging
POST	/v2/sites/{site}/staging/push	Push staging over production
DELETE	/v2/sites/{site}/staging	Delete the staging environment

{site} is always the production site

Every call is addressed to the production site ID, in both sync directions. You never pass the staging site's own ID. InstaWP resolves the staging site from its production site.

Authenticate with your API token as a bearer token:

Authorization: Bearer <api_token>

Create a staging environment

curl -X POST "https://app.instawp.io/api/v2/sites/{site}/staging" \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json"

The work continues in the background. Creation usually takes 2 to 3 minutes, and an email is sent when the staging site is ready.

Common refusals:

• 403 - the site's plan does not include staging, or the site is not eligible (a WaaS site, or a site assigned to a client portal).
• 409 - a staging environment is already being created for this site.
• 422 - this site already has a staging environment. A site can only have one.

Pull production down to staging

curl -X POST "https://app.instawp.io/api/v2/sites/{site}/staging/reset" \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json"

This replaces the staging site's files and database with a fresh copy of production. Anything on staging is overwritten. Production is not touched. The staging site keeps its URL and its SSH credentials.

Push staging to production

curl -X POST "https://app.instawp.io/api/v2/sites/{site}/staging/push" \
  -H "Authorization: Bearer <api_token>" \
  -H "Content-Type: application/json"

There is no automatic undo, and no backup is taken first

A push replaces your live site with the staging copy. We do not take a snapshot of production before it runs, and there is no call that puts the old live site back.

Take your own backup of the production site before you call this if you want a way back. This matters more over the API than in the dashboard, because there is no confirmation dialog in the way.

Two more things to expect after a push:

• Password protection is switched off on the production site and is not re-applied.
• Mapped domains, the CDN pull zone, SSL, tags, SSH keys, the plan and site settings stay on production and are not overwritten. A site with a mapped primary domain keeps serving that domain.

The CDN cache for the production site is purged once the push completes.

Delete a staging environment

curl -X DELETE "https://app.instawp.io/api/v2/sites/{site}/staging" \
  -H "Authorization: Bearer <api_token>"

The staging site and everything on it are removed permanently. The production site is not affected.

Sequencing your calls

A pull and a push cannot run at the same time, and a delete is refused while either is still running. If you are scripting these, wait for one sync to finish before you start the next, rather than firing both and hoping. The Developer Tools > Staging Site page shows whether a sync is in progress.

Related Articles

• Staging Environment for Hosted Sites - What a staging environment includes, and what it does not
• Pull and Push Your Staging Site - The same actions from the dashboard
• Create an API Token - Get a token
• API Overview - How the InstaWP API works
• InstaWP API Documentation - The complete endpoint reference