Publish Appearance Changes
Write theme, appearance, themeOverrides and the brand (name, logo, favicon) to the project's config as a pull request, a commit, or a hosted save
Writes theme, appearance, themeOverrides, name, logo and favicon
to the project's syntext.json (or syntext.yml). By default it opens a pull
request.
Needs a session token and the project admin role (an org admin or the owner).
Request Body
Send at least one of theme, appearance, themeOverrides, name, logo
and favicon. Each one you send replaces that key in the file; null
removes it. Keys you leave out are not touched.
theme"@acme/brand", "@acme/brand@3") or a v1 theme. At most 200 characters.appearanceappearance block to write.themeOverridesthemeOverrides block to write.namelogo{ light?, dark?, type? } with type "mark" or "wordmark" — see logo. Each URL is a path on the site, an http:// or https:// URL (such as one from Upload Brand Asset) or an image data: URL, up to 2048 characters.faviconlogo.targetpr opens a pull request; commit commits straight to the project's branch and needs deploy rights. Ignored for a project without a repository."pr"messagedocs: update appearance in <file>.baseCommitfile.commit from Get Appearance. If the file has changed on the branch since, the request fails with 409 CONFLICT instead of overwriting someone else's change.What happens
| Project | target | Result |
|---|---|---|
| With a repository | pr (default) | A syntext/appearance-… branch with one commit and a pull request against the project's branch. Admins can do this |
| With a repository | commit | One commit on the project's branch, then a build. Needs deploy rights |
| Without a repository | — | The values — brand included — are saved to the project's settings and a build starts from its last published source. Needs deploy rights |
Deploy rights: the owner always has them. An admin has them unless an enabled approval gate on the project names approver roles that leave admins out.
The file keeps its formatting: JSON keeps its indentation, key order and untouched keys exactly; YAML keeps its comments. Settings with validation errors are refused; warnings (such as a failing contrast check) are not.
A build that can't be started after a commit or hosted save never fails the
request — the change is already saved, and buildId is left out.
Response
modepr, commit or hosted.urlhosted.commitShahosted.buildIdError Responses
| Status | Code | When |
|---|---|---|
| 400 | no_changes | None of theme, appearance, themeOverrides, name, logo, favicon was sent, or the file already has these values |
| 400 | invalid_appearance | The settings have a validation error — including a brand URL that isn't a site path, http(s):// or an image data: URL. details.issues lists them |
| 400 | config_unreadable | The config file in the repository doesn't parse. details.path names it |
| 402 | USAGE_LIMIT_EXCEEDED | A hosted save's build would exceed the plan's monthly build limit |
| 403 | admin_required | You're a member, not an admin |
| 403 | deploy_rights_required | target: "commit" or a hosted save without deploy rights. Open a pull request instead |
| 404 | not_found | The project doesn't exist, or you're not in its organization |
| 409 | CONFLICT | baseCommit is stale, or the file changed while writing. details has currentCommit and current (the file's theme, appearance and themeOverrides now) |
| 409 | branch_protected | GitHub refused a direct commit — the branch is probably protected. Open a pull request instead |
| 502 | github_error | GitHub refused the change. Try again |