# Provision a WordPress site and publish to it

Take a domain from "just registered" to "live WordPress site with content" without ever opening a dashboard: provision **Cloud for WordPress**, mint a WordPress credential scoped for automation, then publish over the WordPress REST API.

## 1. Pick a plan

```bash
curl -s https://api.porkbun.com/api/json/v3/hosting/plans \
  -H "X-API-Key: pk1_..." -H "X-Secret-API-Key: sk1_..."
```

Rows where `product` is `cloudWordPress` are WordPress plans (`CLOUDWORDPRESSM1` = Starter monthly, $12.00/mo). Note the `sku` and the `price` in cents — you pass both to the next call.

## 2. Provision the site

```bash
curl -X POST https://api.porkbun.com/api/json/v3/hosting/create/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...",
       "sku":"CLOUDWORDPRESSM1",
       "acknowledgedCost":1200,
       "agreeToTerms":"yes",
       "agreeToNameserverChange":true}'
```

- `acknowledgedCost` must equal the plan price in cents — it forces the cost to be surfaced to the human before anything auto-renews.
- Provisioning switches the domain to Porkbun nameservers, so `agreeToNameserverChange` is required unless it's already on them.
- The domain's **first** provision is a 15-day free trial (nothing charged now) that auto-renews at the plan price. One free trial per domain.
- Add `"dryRun":true` first to validate everything without provisioning or charging.

The response includes `hosting.status` and, for WordPress plans, `hosting.wordpress.restUrl` + `adminUrl`. If `status` is `PENDING`, poll `GET /hosting/get/example.com` until it is `ACTIVE`.

## 3. Edit the site (no credentials needed)

The simplest way to change content is to have Porkbun run the WordPress REST API call
inside the site for you. No password is created, so this works from the Claude app and
ChatGPT too (MCP: `wordpress_request` and `wordpress_upload_media`).

```bash
# list pages
curl -X POST https://api.porkbun.com/api/json/v3/hosting/wpRequest/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","path":"/wp/v2/pages","query":{"_fields":"id,title,link"}}'

# publish a post
curl -X POST https://api.porkbun.com/api/json/v3/hosting/wpRequest/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","method":"POST","path":"/wp/v2/posts",
       "body":{"title":"Hello from the API","content":"<p>Published programmatically.</p>","status":"publish"}}'

# add an image (WordPress downloads it)
curl -X POST https://api.porkbun.com/api/json/v3/hosting/wpUploadMedia/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","url":"https://example.org/photo.jpg","altText":"Our storefront"}'
```

`path` is any REST route without `/wp-json`; `query` and `body` are passed through. The
answer is WordPress's own JSON in `data`, with `httpStatus`. To edit a page, read it with
`{"context": "edit"}`, change `content.raw` (block markup, keep the `<!-- wp:... -->`
comments) and send it back with `POST /wp/v2/pages/{id}`.

It acts as the `porkbun-agent` **editor** by default (pages, posts, media, comments,
menus). Site settings such as the title and tagline, plugins, themes and users need
`"asAdministrator": true` plus `"acknowledgeFullAccess": true`. Each call takes a few
seconds; use `_fields` and `per_page` to keep answers small.

## 3b. Or mint a credential for your own HTTP calls

```bash
curl -X POST https://api.porkbun.com/api/json/v3/hosting/createWpCredentials/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","name":"My-Agent"}'
```

This creates a WordPress **Application Password** and returns it **once** — store it immediately, because WordPress keeps only a hash.

This works on any Cloud for WordPress site in the account — it doesn't matter whether the API or the website provisioned it. (Free $0 preview/parked sites are excluded and return `PREVIEW_SITE_NOT_SUPPORTED`; upgrade to a paid plan first.)

By default it belongs to a dedicated `porkbun-agent` user with the **editor** role: it can create and edit content but **cannot install plugins or change site settings**. That's the right credential for an automated integration. If you genuinely need full control, pass `"role":"administrator"` plus `"acknowledgeFullAccess":true` — an administrator application password can install plugins, which means it can run arbitrary code on the site. (The site's actual administrator account is looked up rather than assumed, so a renamed admin user is handled.)

## 4. Publish

Authenticate to the REST API with HTTP Basic using the username and application password (the response also hands you a ready-made `authorization` header value):

```bash
curl -X POST https://example.com/wp-json/wp/v2/posts \
  -u "porkbun-agent:<applicationPassword>" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello from the API","content":"<p>Published programmatically.</p>","status":"publish"}'
```

From here the whole [WordPress REST API](https://developer.wordpress.org/rest-api/) is available — posts, pages, media, categories, comments.

## 5. Audit and revoke

```bash
# list (metadata only — passwords can never be re-read)
curl -s "https://api.porkbun.com/api/json/v3/hosting/getWpCredentials/example.com" \
  -H "X-API-Key: pk1_..." -H "X-Secret-API-Key: sk1_..."

# revoke one, or all for a user
curl -X POST https://api.porkbun.com/api/json/v3/hosting/deleteWpCredentials/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","uuid":"<uuid from the list>"}'
```

Revocation takes effect immediately. The owner can also see and remove these under **Users → Profile → Application Passwords** in wp-admin.

## 6. Look after the site

`GET /hosting/get/example.com` includes `wordpress.site`: the PHP version and
the versions you can switch to, the WordPress version setting, SSL, storage
used, search visibility, any staging copy, and recent background jobs.

- **PHP:** `POST /hosting/setPhpVersion/example.com` with `{"version": "8.3"}`
  (one of `availablePhpVersions`). If the site breaks, switch back the same way.
- **WordPress:** `POST /hosting/setWordPressVersion/example.com` with
  `"latest"`, or `"previous"` to hold one major release back after an update
  breaks something. Set `"latest"` again once it is fixed, or the site stops
  getting releases.
- **SSL stuck:** `POST /hosting/reissueSsl/example.com` (once every 5 minutes).
- **Search engines:** `POST /hosting/setSearchVisibility/example.com` with
  `{"visible": false}` while the site is being built, `true` when it launches.

### Backups

```bash
# newest first (files daily, database hourly, kept 30 days)
curl -s "https://api.porkbun.com/api/json/v3/hosting/backups/example.com?limit=20" \
  -H "X-API-Key: pk1_..." -H "X-Secret-API-Key: sk1_..."

# take one now (one on-demand backup of each type; delete the old one first)
curl -X POST https://api.porkbun.com/api/json/v3/hosting/createBackup/example.com \
  -H 'Content-Type: application/json' -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

Take an on-demand backup before a risky change. To roll back, pick one files
backup and one database backup and dry-run the restore first: it shows the exact
dates the site would go back to.

```bash
curl -X POST https://api.porkbun.com/api/json/v3/hosting/restoreBackup/example.com \
  -H 'Content-Type: application/json' \
  -d '{"apikey":"pk1_...","secretapikey":"sk1_...","fsId":"<files id>","dbId":"<database id>","dryRun":true}'
```

A real restore **replaces the site's files and database**; anything changed
since those backups is lost, so confirm with the person first. It is queued: the
site is down for a few minutes and the account holder is emailed when it is
done. Poll `GET /hosting/get` and watch `wordpress.site.operations` for
`state: "done"`. Add `"staging": true` to any backup call to work on the staging
copy instead.

### Staging: try changes on a copy first

```bash
curl -X POST https://api.porkbun.com/api/json/v3/hosting/createStaging/example.com \
  -H 'Content-Type: application/json' -d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
```

That builds a private copy of the site on a `*.stagebun.com` address (from the
live site, or from a backup pair with `fsId` + `dbId`). It starts password
protected, with outgoing email blocked and search engines asked to stay away,
and takes a few minutes. Poll `GET /hosting/getStaging/example.com` until
`status` is `ACTIVE`; it also returns the URL and the password.

Make changes there in wp-admin (the staging URL and password come back from
`getStaging`). `wpRequest` and `wpUploadMedia` edit the **live** site, not
staging. Then:

- `POST /hosting/publishStaging/example.com` copies staging over the **live**
  site. A fresh backup of live is taken first, so it can be undone with
  `restoreBackup`. Confirm with the person before publishing.
- `POST /hosting/resetStaging/example.com` throws staging away and starts again
  from live.
- `POST /hosting/deleteStaging/example.com` removes it.

Staging settings: `setStagingGate` (`enabled`, `password`), `setStagingGuard`
(`blockEmail`, `blockApiRequests`: keep email blocked so the copy cannot email
real customers) and `setStagingEnvironment` (`staging` or `production`).

## Notes

- The file endpoints (`/hosting/deploy`, `/hosting/files`, `/hosting/makeDir`, `/hosting/deleteFile`) are for **Secure Static Hosting**. On a WordPress site they return `NOT_SUPPORTED_FOR_PRODUCT` — manage content through WordPress instead.
- Application passwords require the site to be served over HTTPS, which Porkbun provisions automatically.
- Hosting is not simulated in the sandbox: a `pk1_sb_` key gets `SANDBOX_UNSUPPORTED` on these endpoints.
- Prefer the least-privilege `editor` credential for agents, and revoke it when the integration is done.
- Per-key scoping applies: if the API key is restricted to specific domains, these calls only work on those domains (`DOMAIN_NOT_ALLOWED` otherwise).
- Velocity limits: 10 provisions and 20 credential mints per account per hour. `dryRun` calls don't count.


---

## More

- Short overview (start here): https://porkbun.com/llms.txt
- Guides (how-tos): https://porkbun.com/llms/guides
- Help articles (knowledge base) as Markdown: https://porkbun.com/llms/kb
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api
