BlueTheme Docs

REST API

The theme's admin screens and front-end features talk to WordPress through the REST API, under /wp-json/bluetheme/v1. You can use the same routes from your own code. Who may call each route, and how its input is checked, is in the security notes.

Calling it

From the dashboard or the site, as the signed-in user: send the REST nonce. wp.apiFetch does it for you:

const { values } = await wp.apiFetch( { path: '/bluetheme/v1/options' } );

Without apiFetch, send the nonce from wp_create_nonce( 'wp_rest' ) in the X-WP-Nonce header.

From another program: use an application password of a user with the right capability:

curl -u "admin:xxxx xxxx xxxx xxxx xxxx xxxx" https://example.com/wp-json/bluetheme/v1/options

Errors come back as WordPress REST errors: { "code": "…", "message": "…", "data": { "status": 403 } }. Public routes that are called too often answer 429 with the code bluetheme_rate_limited.

Routes

Theme Options

Route Method Does
/options GET All values (values, defaults applied) and the stored ones (stored, only what differs from the defaults).
/options POST Saves { values: { field_id: value, … } }. Fields left out keep their value; unknown fields are dropped; each value is cleaned by its field type. Returns the new values.
/options/reset POST Resets { section }, or everything without a section.
/options/import POST Replaces all values with { values }, keeping the site's secrets.
/css/regenerate POST Rebuilds the generated stylesheet.
/fonts/google/download POST Downloads Google Fonts to the site, for local hosting.
/icons GET, POST Lists icon packs; uploads one (a zip of SVG files).
/icons/{id} DELETE Deletes an uploaded icon pack.
/license/activate, /license/deactivate, /license/check-updates POST License key and updates. See the license server API. 
// Turn the back-to-top button on and widen the site.
await wp.apiFetch( {
	path: '/bluetheme/v1/options',
	method: 'POST',
	data: { values: { back_to_top: true, site_width: 1320 } },
} );

Field ids are in the Theme Options reference and in the panel (the export file lists them too).

Builder and templates

Route Method Does
/builder/{id} GET The page's builder document and whether the builder is on ({ document, active }).
/builder/{id} POST Saves { document, active } and records a revision. The document is cleaned first.
/builder/{id}/render POST HTML and CSS of one node, { node } → { html, css }.
/builder/{id}/render-sections POST The same for a list of sections.
/builder/{id}/autosave POST Saves the user's autosave, for Preview.
/builder/{id}/revisions, /builder/{id}/revisions/{rev} GET Revisions with builder data, and one revision's document.
/page-options/{id} GET, POST A post's Page Options.
/templates GET, POST Published templates; creates one.
/templates/{id}/document, /templates/{id}/settings GET, POST A template's layout and its settings (type, display conditions).
/templates/rules, /templates/rules/search GET Choices for display conditions, and search in them.
/library, /library/{id} GET The pre-built sections, and one ready to insert.

The document format is described in builder internals.

Setup wizard and demos

Route Method Does
/demo/catalog GET Demos, the imported one, and whether an import is running.
/demo/import POST Starts an import: { demo, lang, parts }.
/demo/step POST Runs the next step: { done, progress, message }. Call it until done.
/demo/cancel, /demo/remove POST Stops the import; removes the imported demo.
/demo/language POST Adds Persian or English to Polylang (lang).
/demo/keep POST Keeps the imported demo as the site's own content, so another demo can be imported.
/demo/plugins GET, POST Suggested plugins and their state; installs and activates one, { slug }.

WP-CLI does the same from the command line: see demo internals.

Visitors

Route Method Does
/contact POST Sends the popup contact form.
/love/{id} POST Adds a "love" to a post.
/quick-view/{id} GET A product's quick view.
/wishlist GET, POST The signed-in customer's wishlist.
/wishlist/products GET Product cards for a guest's wishlist.
/otp/send, /otp/verify POST One-time-code login. See account.
/otp/test-sms, /otp/test-log POST Admin tests of the SMS settings.

Adding your own routes

Register them in your own namespace (not bluetheme/v1), with a permission_callback that checks a capability, and clean every argument:

add_action( 'rest_api_init', function () {
	register_rest_route( 'mychild/v1', '/notice', array(
		'methods'             => 'GET',
		'permission_callback' => '__return_true',
		'callback'            => fn() => array( 'text' => \BlueTheme\Options\Options::get( 'site_notice_text', '' ) ),
	) );
} );

Public write routes can use the theme's rate limiter: \BlueTheme\Security\RateLimit::hit( 'my-action', 10, HOUR_IN_SECONDS ) returns false once an IP has made 10 calls in an hour, and RateLimit::error() is the matching 429 response.