Riferimento API REST

URL di base e autenticazione#

Ogni route vive sotto la base REST del tuo sito. Invia il token nell’header Authorization:

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

• Se il tuo hosting toglie Authorization, invia lo stesso valore in X-WPCB-Authorization.
• Le richieste devono usare HTTPS; a quelle in HTTP semplice si risponde con 426.
• /health, /install/info e i due script di installazione sono pubblici. Le route di gestione dei token e del plugin accettano solo un amministratore collegato a WordPress, non un token.
• L’elenco aggiornato delle route è sempre in GET /wp-json/wpcb/v1, l’indice standard del namespace di WordPress.

Errori#

Gli errori usano il formato REST di WordPress, con un codice che inizia per wpcb_:

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

Conferma in due passaggi#

Le operazioni distruttive rispondono alla prima chiamata con 428 e un token di conferma, invece di agire:

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

Ripeti la stessa chiamata con confirmation_token impostato su quel valore entro cinque minuti. Il token vale una sola volta, solo per quell’operazione, quell’utente e quella risorsa; per le scritture è legato anche al contenuto esatto, e per il caricamento di un plugin allo slug e all’hash. Il server MCP 1.3 e Xaflo Desktop 2.0 non lo inviano mai da soli: mostrano il riepilogo e aspettano la persona.

I rifiuti di /db/query hanno codici propri, come unsupported_placeholder, unknown_qualifier, cross_database, secret_column, protected_option o protected_table.

Controllo di salute#

GET /health non richiede token e restituisce status, version, plugin_version, wp_version, php_version, site_url, rest_base, time e multilingual. Inviato con un token valido, restituisce anche i suoi scopes (plugin 1.7.0). Non finisce nel registro delle chiamate.

Novità e modifiche nella 1.7.0#

• POST /admin/login-link (scope admin:login, amministratore) restituisce {url, expires_in: 60}, un link di accesso monouso; il redirect_to facoltativo deve essere un percorso dentro wp-admin. GET /admin/login-link/redeem è pubblico e funziona una volta.
• POST /plugins/install-zip accetta anche zip_base64, filename e sha256 al posto di zip_url; l’attivazione solo con activate: true.
• Scritture /fs/*: site:write solo dentro uploads, fs:admin altrove; confirmation_token accettato su write, upload, rename e delete; fs/write restituisce l’id di un backup.
• /media e /media/unused richiedono media:read; /db/query richiede un amministratore; ogni route con token controlla una capability di WordPress.
• GET /plugins riporta gli aggiornamenti disponibili e le descrizioni; i valori di WP-CLI vanno in args.

Tutte le route#

“Richiede” elenca gli scope per ogni metodo, nello stesso ordine. “admin” vuol dire che anche l’utente dietro al token deve poter gestire le opzioni; “sessione admin” vuol dire un amministratore collegato all’amministrazione di WordPress, senza token.

Identità, salute e statistiche#

Articoli, pagine, termini e ricerca#

Media#

SEO#

Analytics#

Multilingua#

Tema#

Plugin#

Impostazioni, menu, widget#

Backup#

Manutenzione e debug log#

File#

Database e WP-CLI#

Accesso rapido#

Amministrazione del plugin#