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

Preview Appearance

Build the site with unsaved appearance settings and deploy it to your own preview URL

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

Starts a real build of the site with unsaved theme, appearance, themeOverrides, name, logo and favicon laid over its config, and deploys it to a preview URL. The production site and the config file are not touched.

Needs a session token and the project admin role.

Request Body

The same as Validate Appearance: theme, appearance, themeOverrides, name, logo and favicon. At least one is required.

Behaviour

•
A project with a repository builds from its branch; a project without one builds from its last published source.
•
Each user has one preview URL per project: https://appearance-preview-<first 8 characters of your user ID>--<project subdomain>.syntext.dev. A new preview replaces your last one.
•
The build counts against the plan's monthly build quota, like any other.

Response

Returns 201 with:

NameDescription
buildId:string
The preview build. Follow it with the Builds API.
url:string
Your preview URL. It serves the new build once the build finishes.

Error Responses

StatusCodeWhen
400no_changesNone of theme, appearance, themeOverrides, name, logo, favicon was sent
400invalid_appearanceThe settings have a validation error
402USAGE_LIMIT_EXCEEDEDThe organization has used its monthly builds
403admin_requiredYou're a member, not an admin
404not_foundThe project doesn't exist, or you're not in its organization
409no_sourceA project without a repository that hasn't been published yet — publish it once, then preview
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/appearance/preview \
-H "Authorization: Bearer <session token>" \
-H "Content-Type: application/json" \
-d '{ "theme": "console", "appearance": { "accent": "#3DDC97" } }'
Responseapplication/json
json
{
"data": {
"buildId": "bld_9f2c1e",
"url": "https://appearance-preview-usr12345--acme-docs.syntext.dev"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext