/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Try Doc Engine v2

Try Doc Engine v2

Build a preview of a site on a doc engine v2 preset, without changing its config

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

Builds the site's current production source with theme set to a v2 preset and deploys it to a fixed preview URL for that preset. The production site and the config file are not touched. The dashboard's Try doc engine v2 card uses this endpoint.

POST needs the project admin role. GET /v1/projects/{projectId}/appearance/v2-preview?preset=<name> reads the same object and is open to any member; without preset it returns the newest preview, or workbench when there is none.

Request Body

NameDescription
preset:stringbody
One of workbench, paper, console, atlas, plain, orbit, grid, margin.
Default"workbench"
rebuild:booleanbody
Start a new build even when a current preview exists.

Behaviour

•
Each preset has one preview per project, at a URL that never changes: https://v2-preview-<preset>--<project subdomain>.syntext.dev.
•
A preview that is still building, or deployed with no newer production deploy since, is reused (200). A failed or out-of-date preview, or rebuild: true, starts a new build (201).
•
A project with a repository builds from its production branch; a project without one builds from its last published source.
•
The build counts against the plan's monthly build quota.

Response

NameDescription
preset:string
The preset of this preview.
branch:string
v2-preview-<preset>.
url:string
The preview URL.
build:object | null
{ id, status, createdAt, completedAt, error } for the preview's build, or null before one exists.
ready:boolean
The preview is deployed and can be opened.
current:boolean
No production deploy has happened since it was built.
created:boolean
POST only: a new build was started.

Errors

StatusCodeWhen
400validation_errorUnknown preset
401unauthorizedNo session token, or an API key
402USAGE_LIMIT_EXCEEDEDNo builds left this month
403admin_requiredA member calls POST
404not_foundThe project is not in your organization
409no_sourceA project without a repository that has never been published
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl --request POST \
--url 'https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview' \
--header 'Authorization: Bearer <jwt>' \
--header 'Content-Type: application/json' \
--data '{
"preset": "workbench",
"rebuild": true
}'
Responseapplication/json
json
{
"data": {
"preset": "workbench",
"branch": "v2-preview-workbench",
"url": "https://v2-preview-workbench--acme-docs.syntext.dev",
"build": { "id": "b1", "status": "building", "createdAt": "2026-11-13T15:02:11Z", "completedAt": null, "error": null },
"ready": false,
"current": true,
"created": true
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext