API: getting started

Create a token, call https://app.wpforeman.com/api/v1, and read the conventions every endpoint follows.

Updated Oct 11, 2026

The WP Foreman API lets your own scripts and tools (Zapier, Make, a reporting dashboard, an AI agent) do what you do in the app: list sites, run backups, restore, clone, and install or update plugins.

1. Create a token

  1. In the app, open Settings › API tokens.
  2. Give the token a name and tick what it’s allowed to do (its abilities).
  3. Click Create token and copy it straight away. It’s shown once.
Ability Allows
read Read sites, clients, backups, restores, updates and activity
sites Add sites and clients, refresh inventory
backups Run backups, change backup settings, build .zip downloads
restore Restore and clone backups (overwrites sites)
plugins Install, activate, update and delete plugins, themes and WordPress
webhooks Subscribe and unsubscribe webhooks
rules Create, change, delete and run rules

Treat tokens like passwords. Give each tool its own token with only the abilities it needs, and revoke it from Settings › API tokens if it leaks. Tokens start with wpf_ so secret scanners can spot them.

2. Make a request

Send the token as a Bearer token. Everything is JSON.

curl https://app.wpforeman.com/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "data": {
    "id": 1, "name": "Nate", "email": "[email protected]", "timezone": "America/New_York",
    "token": { "name": "Zapier", "abilities": ["read"] }
  }
}

Conventions

  • Base URL: https://app.wpforeman.com/api/v1
  • Responses wrap results in data. Lists that can grow (backups, restores, activity) are paged: ?page=2&per_page=50 (max 100), with meta.page, meta.last_page and meta.total.
  • Long jobs (backups, restores, clones, updates, installs) answer 202 Accepted with the job record. Poll its URL until status is succeeded, partial or failed.
  • Dates are ISO 8601 in UTC.
  • Rate limit: 120 requests a minute per token. Over that you get 429; wait and retry.

Errors

Status Meaning
401 Missing or revoked token
403 The token doesn’t have the ability this needs
404 Not found, or not yours
409 Can’t right now: site busy (a backup, restore or update is running), not connected, or the plugin is too old
422 Invalid input; errors lists each field
429 Rate limited

Every error has a human-readable message:

{ "message": "A backup, restore or update is already running on Shop." }

Safety

The API follows the same rules as the app: a safety backup runs before every restore and clone, updates and deletes back up first unless you send "backup_first": false, the WP Foreman plugin is never overwritten, and wp-config.php is left alone unless you send "include_wp_config": true. The app’s type-the-domain confirmation is replaced by the restore ability, so only give that ability to tools you trust.

Was this helpful?