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
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
presetOne of
workbench, paper, console, atlas, plain, orbit, grid, margin.Default
"workbench"rebuildStart 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
presetThe preset of this preview.
branchv2-preview-<preset>.urlThe preview URL.
build{ id, status, createdAt, completedAt, error } for the preview's build, or null before one exists.readyThe preview is deployed and can be opened.
currentNo production deploy has happened since it was built.
createdPOST only: a new build was started.Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | Unknown preset |
| 401 | unauthorized | No session token, or an API key |
| 402 | USAGE_LIMIT_EXCEEDED | No builds left this month |
| 403 | admin_required | A member calls POST |
| 404 | not_found | The project is not in your organization |
| 409 | no_source | A project without a repository that has never been published |
Was this page helpful? Yes No
Previous
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
}'
const response = await fetch('https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview', {
method: 'POST',
headers: {
'Authorization': 'Bearer <jwt>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"preset": "workbench",
"rebuild": true
}),
});
const data = await response.json();
console.log(response.status, data);
import requests
url = "https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview"
headers = {
"Authorization": "Bearer <jwt>",
}
payload = {
"preset": "workbench",
"rebuild": True,
}
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(`{
"preset": "workbench",
"rebuild": true
}`)
req, err := http.NewRequest("POST", "https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview", bytes.NewReader(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer <jwt>")
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/{projectId}/appearance/v2-preview")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <jwt>"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"preset" => "workbench",
"rebuild" => true,
})
response = http.request(request)
puts response.code
puts response.body
<?php
$payload = [
'preset' => 'workbench',
'rebuild' => true,
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview',
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <jwt>',
'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 = """
{
"preset": "workbench",
"rebuild": true
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.syntext.dev/v1/projects/{projectId}/appearance/v2-preview"))
.header("Authorization", "Bearer <jwt>")
.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/{projectId}/appearance/v2-preview");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer <jwt>");
request.Content = new StringContent(
"""
{
"preset": "workbench",
"rebuild": true
}
""",
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": {
"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
}
}