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

Validate Appearance

Check unsaved appearance settings: issues, accent contrast and the normalized values that would be written

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

Resolves unsaved settings without saving anything, and returns the problems, the accent contrast checks and the normalized settings that Publish Appearance Changes would write.

Any member of the project's organization can call it, with a session token.

Request Body

NameDescription
theme:stringbody
A preset name ("paper"), an organization theme ("@acme/brand", "@acme/brand@3") or a v1 theme. At most 200 characters.
appearance:objectbody
An appearance block.
themeOverrides:objectbody
A themeOverrides block. Unknown tokens come back as warnings.
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.

Response

NameDescription
appearance:object
The resolved appearance, as in Get Appearance.
sources:object
The source of every value.
issues:array
{ path, severity, message }. An error would make publishing fail with 400 invalid_appearance; a warning would not. Brand issues use the paths logo, logo.light, logo.dark, logo.type and favicon: a URL with another scheme (javascript:, a non-image data: URL) is an error, and type: "wordmark" with no logo image is a warning, since the name would still show.
contrast:array
One entry per mode and check: { mode, check, ratio, required, passes, suggestion? }. check is link (needs 4.5:1) or fill (needs 3:1); suggestion is the nearest passing shade of the accent when the check fails. Failing checks never block publishing.
normalized:object
{ theme?, appearance?, themeOverrides?, name?, logo?, favicon? } — the settings in the form they'd be written to the file: only the fields you set, in a fixed order, with accent collapsed to one colour when both modes match. Brand values are trimmed, empty logo.light / logo.dark are left out, and null (remove) is kept.

Response

appearance and sources are abbreviated.

Error Responses

StatusCodeWhen
400validation_errorThe body isn't an object of the shape above
404not_foundThe project doesn't exist, or you're not in its organization
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate \
-H "Authorization: Bearer <session token>" \
-H "Content-Type: application/json" \
-d '{ "theme": "workbench", "appearance": { "accent": "#F2B705" } }'
Responseapplication/json
json
{
"data": {
"appearance": { "preset": "workbench", "accent": { "light": "#F2B705", "dark": "#F2B705" } },
"sources": { "accent.light": "appearance", "accent.dark": "appearance" },
"issues": [],
"contrast": [
{ "mode": "light", "check": "link", "ratio": 2.57, "required": 4.5, "passes": false, "suggestion": "#B18604" },
{ "mode": "light", "check": "fill", "ratio": 1.82, "required": 3, "passes": false, "suggestion": "#BB8D04" },
{ "mode": "dark", "check": "link", "ratio": 12.47, "required": 4.5, "passes": true },
{ "mode": "dark", "check": "fill", "ratio": 10.82, "required": 3, "passes": true }
],
"normalized": { "theme": "workbench", "appearance": { "accent": "#F2B705" } }
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext