Kindly EditDocumentationTry the editor

theme-settings REST endpoints

Read, check, save, publish, or discard the client design from Kindly Edit > Theme.

Endpoints#

The routes behind Theme settings (Kindly Edit > Theme), added in 0.9.15. They are registered only when the active theme provides the client design document.

GET  /wp-json/cantata-edit/v1/theme-settings
POST /wp-json/cantata-edit/v1/theme-settings/validate
POST /wp-json/cantata-edit/v1/theme-settings/draft
POST /wp-json/cantata-edit/v1/theme-settings/publish
POST /wp-json/cantata-edit/v1/theme-settings/discard
Route Does
GET /theme-settings Reads the design document (the draft when there is one), with the addresses of its logo and default picture in media.
POST /theme-settings/validate Checks a design object with the theme's validation and returns the result without saving.
POST /theme-settings/draft Saves design as the draft. Needs the current rev.
POST /theme-settings/publish Publishes the saved draft. Needs the current rev.
POST /theme-settings/discard Discards the draft. Needs the current rev.

Permission#

Every route needs manage_options (an administrator):

$can = static fn() => current_user_can( 'manage_options' );

These routes run the same steps as the client design abilities (cantata-edit/get-client-design, save-client-design-draft, publish-client-design, discard-client-design-draft) but as a person on the screen, so they do not need AI access turned on. The abilities still do.

Registered argument schema#

{
  "rev": { "type": "string" },
  "design": { "type": "object" }
}

A stale rev is refused with HTTP 409 (cantata_design_changed), as with the abilities: read the document again rather than forcing the change. Publishing with no draft is refused with cantata_design_no_draft.

Implementation#

includes/kindly-theme.php registers the routes and includes/theme-design.php (cantata_edit_design_manual()) marks a request as coming from the screen.

Client handling#

Use HTTPS on production sites. Treat authentication failures, validation errors, missing records, and stale-revision conflicts as different outcomes. Read the returned WordPress error code and message. Before retrying a timed-out mutation, determine whether the first request succeeded. Prefer the documented higher-level editor or Ability workflow when an endpoint coordinates several metadata owners.

About this page

Documents Kindly Edit 0.9.16. Source: includes/kindly-theme.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.