/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Fix Deprecated Syntax

Fix Deprecated Syntax

Rewrite a project's deprecated syntax — returned as a diff, or saved as one pull request or draft that's never published

POST/v1/projects/{projectId}/deprecations/fixTry it
Session token

Rewrites every use of deprecated syntax in the project's files — config keys, frontmatter keys, MDX tags and props, the config file name and, on a doc engine v2 site, the generated docs home — as stx migrate does. It's what the dashboard's Fix automatically button and the connector's fix_deprecated_syntax use.

A dry run (the default) returns the diff and saves nothing. Otherwise the rewrites are saved as one change, and nothing is published:

ProjectDefaultmode: "commit"
GitHub (connected repository)A pull requestOne commit to the production branch
Written in SyntextAn unpublished draft, opened in the dashboard editorOne new revision

Your _syntext/ custom code is never read or changed.

Authentication

Any member of the project's organization, with a session token, or a project API key with full scope. A key writes as the person who created it and can never commit. mode: "commit" needs a workspace admin or owner.

Up to 10 requests per minute per caller and project.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

NameDescription
dryRun:booleanbody
Return the diff without saving anything.
Defaulttrue
v2:booleanbody
Also apply the moves into appearance (colors.primary, fonts.* and the features style flags). On a v1 site this switches it to doc engine v2 and changes its look. On a site already on v2 they're applied either way.
Defaultfalse
mode:stringbody
pull_request (GitHub projects), draft or commit. Leave it out for the default: a pull request on GitHub, a draft on a project written in Syntext. commit is for workspace admins and owners only, and never with changeId.
changeId:stringbody
Add the fix to an existing unpublished change instead of starting a new one: pr-<number> (a pull request Syntext opened) or draft (a project written in Syntext).

Any other key is refused.

Response

NameDescription
dryRun:boolean
true when nothing was saved on purpose.
source:string
Where the files were read: github or hosted (written in Syntext).
v2:boolean
The v2 you sent.
switchesToV2:boolean
true when the rewrites move a v1 site to doc engine v2.
files:object[]
Each file that changes: path, renamedTo (for syntext.config.json → syntext.json) and diff, a unified diff.
rewritten:object[]
Every rewrite: code, file, line, old, replacement and an optional note.
notRewritten:object[]
Deprecated forms left as they are — the same fields, plus reason and requiresV2 (true when it waits for v2).
remaining:object[]
What the build still reports after the fix (file, line, code, message): unknown keys and forms not rewritten.
home:object | null
The generated docs home: file, converted, and reason when it wasn't converted — for example because the site has no build yet. null when there's no generated home.
notes:string[]
Plain-language notes, such as No deprecated syntax found. or that the fix moves the site to doc engine v2.
change:object | null
The change that was saved — null for a dry run, or when there was nothing to rewrite.
Show 6 child attributesobject | null

Example

Preview the fix:

Then save it:

Error Responses

Errors use { "error": { "code", "message" } }.

StatusCodeWhen
400validation_errorA body field has the wrong type, mode isn't one of its values, or there's a key the endpoint doesn't take
400invalid_modemode: "pull_request" on a project written in Syntext, or mode: "commit" with changeId
400invalid_changechangeId isn't a change ID
401unauthorizedNo session token or API key
403forbiddenYou're not in the project's organization, the API key is below full scope, or mode: "commit" without the admin or owner role
404not_foundThe project doesn't exist, or the API key belongs to another project
409github_permissionThe Syntext GitHub App is missing a permission. The message names the one to grant
409content_source_uploadThe project is published with stx deploy, so its files aren't in Syntext. Run stx migrate in the project folder
409no_repositoryThe project has no connected repository. Connect one, or run stx migrate
409save_conflictA file changed while the fix was being prepared. Nothing was saved — run it again
409invalid_changeThe pull request in changeId doesn't exist, is closed, or wasn't opened by Syntext
409fix_failedThe change couldn't be saved. The message says why
422invalid_configsyntext.json can't be read. Fix it, then run the fix again
422too_many_pagesThe project has more than 1,000 pages. Run stx migrate in a checkout
429rate_limitedMore than 10 requests from you on this project in the current minute. Wait details.retryAfterSeconds
Was this page helpful? Yes No
Request
cURLcURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e/deprecations/fix \
-H "Authorization: Bearer <session token>" \
-H "Content-Type: application/json" \
-d '{}'
Responseapplication/json
json
{
"data": {
"dryRun": false,
"source": "github",
"v2": false,
"switchesToV2": false,
"files": [
{
"path": "docs/changelog.mdx",
"diff": "--- a/docs/changelog.mdx\n+++ b/docs/changelog.mdx\n@@ -12,1 +12,1 @@\n-<Update label=\"June 2026\">\n+<Update title=\"June 2026\">\n"
}
],
"rewritten": [
{
"code": "mdx.update-label",
"file": "docs/changelog.mdx",
"line": 12,
"old": "<Update label=\"…\">",
"replacement": "<Update title=\"…\">"
}
],
"notRewritten": [
{
"code": "config.fonts-heading",
"file": "syntext.json",
"line": 9,
"old": "fonts.heading: \"Inter\"",
"replacement": "appearance.fonts.heading: \"Inter\"",
"reason": "Moves the value into appearance, which switches the site to doc engine v2. Turn on the doc engine v2 option to apply it.",
"requiresV2": true
}
],
"remaining": [],
"home": null,
"notes": [
"1 change moves values into appearance, which switches the site to doc engine v2; it waits for the doc engine v2 option."
],
"change": {
"mode": "pull_request",
"changeId": "pr-57",
"url": "https://github.com/acme/docs/pull/57",
"pullRequestNumber": 57,
"previewUrl": null
}
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext