/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Publish Appearance Changes

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

POST/v1/projects/{projectId}/appearance/changesTry it
Session token

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.

NameDescription
theme:string | nullbody
A preset, an organization theme ("@acme/brand", "@acme/brand@3") or a v1 theme. At most 200 characters.
appearance:object | nullbody
The whole appearance block to write.
themeOverrides:object | nullbody
The whole themeOverrides block to write.
name:string | nullbody
The site name, 1–120 characters.
logo:string | object | nullbody
One URL, or { 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.
favicon:string | nullbody
The favicon URL, with the same rules as logo.
target:stringbody
pr opens a pull request; commit commits straight to the project's branch and needs deploy rights. Ignored for a project without a repository.
Default"pr"
message:stringbody
Commit message and pull request title, up to 500 characters. Defaults to docs: update appearance in <file>.
baseCommit:stringbody
The file.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

ProjecttargetResult
With a repositorypr (default)A syntext/appearance-… branch with one commit and a pull request against the project's branch. Admins can do this
With a repositorycommitOne 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

NameDescription
mode:string
pr, commit or hosted.
url:string
The pull request URL, or the commit URL. Absent for hosted.
commitSha:string
The commit that was written. Absent for hosted.
buildId:string
The build started by a commit or hosted save.

Error Responses

StatusCodeWhen
400no_changesNone of theme, appearance, themeOverrides, name, logo, favicon was sent, or the file already has these values
400invalid_appearanceThe 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
400config_unreadableThe config file in the repository doesn't parse. details.path names it
402USAGE_LIMIT_EXCEEDEDA hosted save's build would exceed the plan's monthly build limit
403admin_requiredYou're a member, not an admin
403deploy_rights_requiredtarget: "commit" or a hosted save without deploy rights. Open a pull request instead
404not_foundThe project doesn't exist, or you're not in its organization
409CONFLICTbaseCommit is stale, or the file changed while writing. details has currentCommit and current (the file's theme, appearance and themeOverrides now)
409branch_protectedGitHub refused a direct commit — the branch is probably protected. Open a pull request instead
502github_errorGitHub refused the change. Try again
json
{
"error": {
"code": "CONFLICT",
"message": "The configuration changed on the default branch since the editor opened it. Review the current values and try again.",
"details": {
"currentCommit": "a1b2c3d",
"current": { "theme": "paper", "appearance": { "accent": "#0F766E" }, "themeOverrides": null }
}
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/changes \
-H "Authorization: Bearer <session token>" \
-H "Content-Type: application/json" \
-d '{
"theme": "paper",
"appearance": { "accent": "#0E7A63", "radius": "small" },
"message": "Switch docs to the Paper preset",
"baseCommit": "4f1c2a9"
}'
Responseapplication/json
json
{
"data": {
"mode": "pr",
"url": "https://github.com/acme/docs/pull/42",
"commitSha": "9b8e7d6c5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext