/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Convert the Home to Content

Convert the Home to Content

Write the index page's generated docs home as home components — returned as a preview, committed, or opened as a pull request

POST/v1/projects/{projectId}/appearance/home/convertTry it
Session token

Writes the generated docs home of the index page as home components (<Hero>, <SectionCards> and the rest), so the page gets back the look the generated home gave it — since 16 November 2026, a doc engine v2 index page shows only its own content. It's what the dashboard's Convert home to content button (on the deprecation banner) and stx migrate use.

Needs a session token. Any member of the project's organization can ask for a preview; commit and pr need the project admin role, and commit also needs deploy rights.

Request Body

NameDescription
target:stringbody
preview returns the new page without writing anything. commit commits it to the project's branch and starts a build. pr opens a syntext/home-content-… branch and a pull request against the project's branch.
Default"preview"
message:stringbody
Commit message and pull request title, up to 500 characters. Defaults to docs: write the docs home as components in <file>.

Where the page is read from

The index page is read from the project's repository. A preview for a project without a repository — or one whose repository can't be read — falls back to the last production build's source bundle, then to the components alone from the last build. Writing (commit or pr) always needs the repository.

Response

NameDescription
mode:string
preview, commit or pr.
from:string
Where the index page was read: repository, source-bundle or last-build.
mdx:string
The home components alone.
source:string
The index page's whole new source, with home dropped from its frontmatter. Absent when from is last-build.
path:string
The index page's file name. Absent when from is last-build.
warnings:string[]
Anything the conversion couldn't carry over exactly.
site:object
The site data the conversion used (the preset's home layout, sections, quickstart and so on), so a local copy of the page can be converted the same way.
url:string
The commit or pull request URL. commit and pr only.
commitSha:string
The commit that was written. commit and pr only.
buildId:string
The build started by a commit. Left out if the build couldn't be started — the commit is already saved.

Error Responses

StatusCodeWhen
400validation_errortarget isn't preview, commit or pr, or message is over 500 characters
400no_repositorycommit or pr on a project without a repository. Ask for the preview and paste the components into the index page
403admin_requiredcommit or pr as a member, not an admin
403deploy_rights_requiredcommit without deploy rights. Use pr instead
404not_foundThe project doesn't exist, or you're not in its organization
404no_indexThe last build, or the repository's branch, has no index page
409already_contentThe index page already shows its own content — it uses the home components or sets home: false
409save_conflictThe index page changed while converting. Try again
502github_errorGitHub refused the request. Try again
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f/appearance/home/convert \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{ "target": "pr" }'
Responseapplication/json
json
{
"data": {
"mode": "pr",
"from": "repository",
"path": "index.mdx",
"mdx": "<Hero title=\"Acme Docs\">\n <SearchBar />\n</Hero>\n\n<SectionCards />\n",
"source": "---\ntitle: Acme Docs\nlayout: wide\n---\n\n<Hero title=\"Acme Docs\">…",
"warnings": [],
"site": { "…": "…" },
"url": "https://github.com/acme/docs/pull/43",
"commitSha": "9b8e7d6c5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext