/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Save Pages

Save Pages

Save one or more files in a single commit or draft revision, with conflict detection.

POST/v1/projects/{projectId}/pages/saveTry it
Session token

Commit up to 100 files to the project's branch in one commit, then start a build. On a project written in Syntext, the files are saved as one draft revision instead, and the site changes only when you publish. Pass the sha each file was opened at and the save is refused — with nothing written — if someone else changed any of them in the meantime.

Note

Any member of the workspace can save, signed in with a session JWT — API keys are refused with 401. You must belong to the organization that owns {projectId}. Available on every plan.

On a GitHub project, the project needs a GitHub App installation that belongs to its workspace, and saves commit straight to the project's branch. A project written in Syntext needs neither.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

NameDescription
files:arraybodyRequired
1–100 files. Each path may appear only once.
Show 3 child attributesarray
message:stringbody
Commit (or revision) message, up to 500 characters. Defaults to docs: update <path>, or docs: update N files (…) for several.
publish:booleanbody
Projects written in Syntext only: publish the project once the draft is saved, as Publish Content does. Ignored on a GitHub project, where every save builds.
Defaultfalse

Response — 200 OK

files[].sha is each file's new blob sha. Keep it and send it with your next save, so that save is conflict-checked too without re-reading the file.

A build of the branch is queued after the commit. If queuing it fails, the save still succeeds.

build says what happened: { id, status } for the queued build, { skipped: "usage_limit", current, limit } when the plan's builds for the month are used up, or null when no build was started or queuing it failed.

Projects written in Syntext

The save is a draft revision. revision is { id, number } and commitSha is the revision's id; files[].sha work the same way. A save that changes nothing writes no revision: revision is null and commitSha empty. build is null unless you sent publish: true:

The project holds at most 2,000 files and 200 MB — a save past either returns 413 too_many_files or 413 content_too_large. A text file over 1 MB returns 413 file_too_large, and an image path returns 400 unsupported_file_type: upload images with Import Content. If the project moved to GitHub while you were editing, the save returns 409 content_source_github; reload and edit it there.

Conflicts

The save is refused with 409 save_conflict when a sha you sent no longer matches the file on the branch, or when the branch moved between Syntext reading it and writing to it. Nothing is committed and no build is started.

json
{
"error": {
"code": "save_conflict",
"message": "guides/quickstart.mdx was changed by someone else since you opened it. Reload it or keep your version.",
"details": {
"paths": ["guides/quickstart.mdx"],
"files": [
{
"path": "guides/quickstart.mdx",
"currentSha": "5e7a9c1b3d5f7e9a1c3b5d7f9e1a3c5b7d9f1e3a",
"lastCommit": { "author": "Ada Lovelace", "at": "2026-11-08T15:52:10Z" }
}
],
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
•
details.paths lists every conflicting file.
•
details.files[].currentSha is the file's sha on the branch now, or null when it was deleted — or when the conflict was the branch moving, which is not tied to one file.
•
details.files[].lastCommit names who last committed to the file and when. It is included for at most the first five files, and left out when it cannot be looked up.

To resolve, re-read the file, merge, and save again with the new sha — or omit sha to overwrite.

Error Responses

400 Bad Request

validation_error — the same path appears twice in files.

invalid_path — a path is absolute, contains a backslash or a control character, or has an empty, . or .. segment. details.path names it.

bad_request — the project has no repository, an invalid repository URL, or no GitHub App installation.

A body that fails schema validation — no files, more than 100, an empty path, or a message over 500 characters — gets 400 validation_error, with each problem in details.issues.

401 Unauthorized

No session JWT, an expired one, or an API key.

403 Forbidden

forbidden — you are not a member of the organization that owns the project.

installation_not_owned — the project's GitHub App installation is not connected to its workspace.

404 Not Found

not_found — the project does not exist or was deleted, or GitHub cannot find the repository or branch.

409 Conflict

save_conflict — see Conflicts.

content_source_upload — the project is published with stx deploy, so its files aren't stored in Syntext. Import them first (Import Content) to edit them here.

500 Internal Server Error

internal_error — the GitHub integration is temporarily unavailable.

502 Bad Gateway

github_error — GitHub refused the request. details.githubStatus is GitHub's HTTP status; GitHub's own response body is not passed through. Retry, and check the installation's permissions if it persists.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/pages/save \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"files": [
{
"path": "guides/quickstart.mdx",
"content": "---\ntitle: Quickstart\n---\n\n# Quickstart\n...",
"sha": "3f1c9a7e2b4d6f8a0c1e3b5d7f9a1c3e5b7d9f1a"
},
{ "path": "guides/next-steps.mdx", "content": "---\ntitle: Next steps\n---\n" }
],
"message": "docs: refresh quickstart"
}'
Request
jsoncURLJavaScriptPythonGoRubyPHPJavaC#json
{
"data": {
"commitSha": "5b0f9c1e-7a2d-4e8b-9c3f-1d6a8e2b4c70",
"files": [{ "path": "guides/quickstart.mdx", "sha": "c2a8e4f6b0d1c3e5a7b9d1f3e5c7a9b1d3f5e7c9" }],
"revision": { "id": "5b0f9c1e-7a2d-4e8b-9c3f-1d6a8e2b4c70", "number": 12 },
"build": null
}
}
Responseapplication/json
200OK
{
"data": {
"commitSha": "9d4e1b7c3a5f8e2d6b0c4a9f1e7d3b5c8a2f6e0d",
"files": [
{ "path": "guides/quickstart.mdx", "sha": "c2a8e4f6b0d1c3e5a7b9d1f3e5c7a9b1d3f5e7c9" },
{ "path": "guides/next-steps.mdx", "sha": "7b3d5f9a1c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d" }
],
"build": { "id": "b2f1c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "status": "queued" }
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext