API Reference Validate Appearance
Validate Appearance
Check unsaved appearance settings: issues, accent contrast and the normalized values that would be written
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
themeA preset name (
"paper"), an organization theme ("@acme/brand", "@acme/brand@3") or a v1 theme. At most 200 characters.appearanceAn
appearance block.themeOverridesA
themeOverrides block. Unknown tokens come back as warnings.nameThe site name, 1–120 characters.
logoOne 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.faviconThe favicon URL, with the same rules as
logo.Response
NameDescription
appearanceThe resolved appearance, as in Get Appearance.
sourcesThe source of every value.
issues{ 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.contrastOne 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{ 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
| Status | Code | When |
|---|---|---|
| 400 | validation_error | The body isn't an object of the shape above |
| 404 | not_found | The project doesn't exist, or you're not in its organization |
Was this page helpful? Yes No
Previous
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" } }'
const response = await fetch('https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate', {
method: 'POST',
headers: {
'Authorization': 'Bearer <session token>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"theme": "workbench",
"appearance": {
"accent": "#F2B705"
}
}),
});
const data = await response.json();
console.log(response.status, data);
import requests
url = "https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate"
headers = {
"Authorization": "Bearer <session token>",
}
payload = {
"theme": "workbench",
"appearance": {
"accent": "#F2B705",
},
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"theme": "workbench",
"appearance": {
"accent": "#F2B705"
}
}`)
req, err := http.NewRequest("POST", "https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate", bytes.NewReader(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer <session token>")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status)
fmt.Println(string(body))
}
require "json"
require "net/http"
require "uri"
uri = URI("https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <session token>"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"theme" => "workbench",
"appearance" => {
"accent" => "#F2B705",
},
})
response = http.request(request)
puts response.code
puts response.body
<?php
$payload = [
'theme' => 'workbench',
'appearance' => [
'accent' => '#F2B705',
],
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate',
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <session token>',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status, PHP_EOL, $response, PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String payload = """
{
"theme": "workbench",
"appearance": {
"accent": "#F2B705"
}
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate"))
.header("Authorization", "Bearer <session token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http;
using System.Text;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/validate");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer <session token>");
request.Content = new StringContent(
"""
{
"theme": "workbench",
"appearance": {
"accent": "#F2B705"
}
}
""",
Encoding.UTF8,
"application/json");
using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
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" } }
}
}