REST API reference

Base URL and authentication#

Every route lives under your site’s REST base. Send a token in the Authorization header:

curl -H "Authorization: Bearer YOUR_TOKEN" 
  https://your-site.example/wp-json/wpcb/v1/whoami

• If your host strips Authorization, send the same value in X-WPCB-Authorization.
• Requests must use HTTPS; plain HTTP is answered with 426.
• /health, /install/info and the two installer scripts are public. Token and plugin administration routes accept only a logged-in WordPress administrator, not a token.
• The live list of routes is always at GET /wp-json/wpcb/v1, the standard WordPress namespace index.

Errors#

Errors use the WordPress REST format, with a code that starts with wpcb_:

{
  "code": "wpcb_rate_limited",
  "message": "…",
  "data": { "status": 429, "retry_after": 12, "limit": 60, "scope_limited": "__global__" }
}

Two-step confirmation#

Destructive operations answer the first call with 428 and a confirmation token instead of acting:

{
  "error": {
    "code": "wpcb_confirmation_required",
    "message": "Provide confirmation_token to restore.",
    "confirmation_token": "ct_…",
    "expires_at": "…",
    "operation_summary": "…"
  }
}

Repeat the same call with confirmation_token set to that value within five minutes. The token works once, for that operation, user and resource only; for writes it is also bound to the exact content, and for a plugin upload to the slug and the hash. MCP server 1.3 and Xaflo Desktop 2.0 never send it by themselves: they show the summary and wait for the person.

/db/query refusals carry their own codes, such as unsupported_placeholder, unknown_qualifier, cross_database, secret_column, protected_option or protected_table.

Health check#

GET /health needs no token and returns status, version, plugin_version, wp_version, php_version, site_url, rest_base, time and multilingual. Sent with a valid token, it also returns that token’s scopes (plugin 1.7.0). It is not written to the audit log.

New and changed in 1.7.0#

• POST /admin/login-link (scope admin:login, administrator) returns {url, expires_in: 60}, a one-time sign-in link; an optional redirect_to must be a path under wp-admin. GET /admin/login-link/redeem is public and works once.
• POST /plugins/install-zip also accepts zip_base64, filename and sha256 instead of zip_url; activation only with activate: true.
• /fs/* writes: site:write inside uploads only, fs:admin elsewhere; confirmation_token accepted on write, upload, rename and delete; fs/write returns a backup id.
• /media and /media/unused need media:read; /db/query needs an administrator; every token route checks a WordPress capability.
• GET /plugins reports available updates and descriptions; WP-CLI values go in args.

All routes#

“Needs” lists the scopes for each method, in order. “admin” means the user behind the token must also be able to manage options; “admin session” means a logged-in administrator in the WordPress admin, with no token.

Identity, health and stats#

Posts, pages, terms and search#

Media#

SEO#

Analytics#

Multilingual#

Theme#

Plugins#

Settings, menus, widgets#

Backups#

Maintenance mode and debug log#

Files#

Database and WP-CLI#

Quick login#

Plugin administration#