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
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:
| Project | Default | mode: "commit" |
|---|---|---|
| GitHub (connected repository) | A pull request | One commit to the production branch |
| Written in Syntext | An unpublished draft, opened in the dashboard editor | One 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
projectIdRequest Body
dryRuntruev2appearance (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.falsemodepull_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.changeIdpr-<number> (a pull request Syntext opened) or draft (a project written
in Syntext).Any other key is refused.
Response
dryRuntrue when nothing was saved on purpose.sourcegithub or hosted (written in Syntext).v2v2 you sent.switchesToV2true when the rewrites move a v1 site to doc engine v2.filespath, renamedTo (for syntext.config.json →
syntext.json) and diff, a unified diff.rewrittencode, file, line, old, replacement and an optional
note.notRewrittenreason and
requiresV2 (true when it waits for v2).remainingfile, line, code,
message): unknown keys and forms not rewritten.homefile, converted, and reason when it wasn't
converted — for example because the site has no build yet. null when
there's no generated home.notesNo deprecated syntax found. or that the fix
moves the site to doc engine v2.changenull for a dry run, or when there was nothing
to rewrite.modepull_request, draft or commit.changeIdpr-<number> or draft, to add more to the change. null for a commit.urlpullRequestNumberpreviewUrlrevisionExample
Preview the fix:
Then save it:
Error Responses
Errors use { "error": { "code", "message" } }.
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A body field has the wrong type, mode isn't one of its values, or there's a key the endpoint doesn't take |
| 400 | invalid_mode | mode: "pull_request" on a project written in Syntext, or mode: "commit" with changeId |
| 400 | invalid_change | changeId isn't a change ID |
| 401 | unauthorized | No session token or API key |
| 403 | forbidden | You're not in the project's organization, the API key is below full scope, or mode: "commit" without the admin or owner role |
| 404 | not_found | The project doesn't exist, or the API key belongs to another project |
| 409 | github_permission | The Syntext GitHub App is missing a permission. The message names the one to grant |
| 409 | content_source_upload | The project is published with stx deploy, so its files aren't in Syntext. Run stx migrate in the project folder |
| 409 | no_repository | The project has no connected repository. Connect one, or run stx migrate |
| 409 | save_conflict | A file changed while the fix was being prepared. Nothing was saved — run it again |
| 409 | invalid_change | The pull request in changeId doesn't exist, is closed, or wasn't opened by Syntext |
| 409 | fix_failed | The change couldn't be saved. The message says why |
| 422 | invalid_config | syntext.json can't be read. Fix it, then run the fix again |
| 422 | too_many_pages | The project has more than 1,000 pages. Run stx migrate in a checkout |
| 429 | rate_limited | More than 10 requests from you on this project in the current minute. Wait details.retryAfterSeconds |