Render one of the site's own pages with unsaved appearance and brand settings, without a build
POST/v1/projects/{projectId}/appearance/renderTry it
Session token
Renders one real page of the project's site with unsaved settings laid over
its config, and returns the HTML. It's what the
appearance editor shows when you
pick a page under Your pages. Nothing is saved and no build runs.
Any member of the project's organization can call it — it's read-only. It
needs a session token; API keys get 401. A caller outside the organization
gets 404.
How it works
Every production build saves what it knew about each page and the site's
shell: the compiled pages, sidebar, sections, table of contents and site data.
This endpoint renders the page from that snapshot with the doc engine v2
renderer, using the same appearance and token resolution as the build. The
result is the page your next build would publish with these settings — for
content as of the last production build.
•
Page content, and pages added since, are from that build. Unpublished edits don't show.
•
Code highlighting was done by that build, so code colours are from that build too.
•
A project that has never had a production build, or whose last one ran before this endpoint existed, returns 409 no_source. Publish (or rebuild) once.
Path Parameters
NameDescription
projectId:stringpathRequired
The project ID.
Request Body
Only path is required. Every other key you send is laid over the project's
config for this render; null removes that key, and keys you leave out keep
the config's value.
NameDescription
path:stringbodyRequired
The page to render, as returned by List Preview Pages. /guides/x, guides/x, /guides/x/ and /guides/x?y#z all name the same page; /index is /. Up to 1024 characters.
theme:string | nullbody
A preset, an organization theme ("@acme/brand", "@acme/brand@3") or a v1 theme. At most 200 characters.
One URL, or { light?, dark?, type? } with type"mark" or "wordmark" — see logo. URLs are up to 2048 characters.
favicon:string | nullbody
The favicon URL, up to 2048 characters.
mode:stringbody
light or dark: render in this mode instead of the resolved appearance.mode.
A name, logo or favicon value with a validation error (for example a
javascript: URL) is left out of the render rather than failing it — check
it with Validate Appearance. With no
logo set anywhere, the page shows the Syntext mark, as the build does.
Response
NameDescription
html:string
The complete HTML document for the page. Relative links and images resolve against the live site, through a <base href> set to the site's URL.
Renders are cached per build, page and settings, so asking again for the same
combination is fast.
Error Responses
Status
Code
When
400
validation_error
The body isn't an object of the shape above
401
unauthorized
No session token, or an API key
404
not_found
The project doesn't exist, or you're not in its organization
404
page_not_found
The last build has no page at path. details.path is the normalized path
409
no_source
Nothing to render from. details.reason is never_built or not_captured — see List Preview Pages
json
{
"error": {
"code": "page_not_found",
"message": "The site has no page at /guides/old-page.",