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.