Save Pages
Save one or more files in a single commit or draft revision, with conflict detection.
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.
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
projectIdRequest Body
filespathguides/quickstart.mdx. The repository-root config files syntext.json, syntext.yaml, syntext.yml and syntext.config.json are addressed by their bare name. See Paths.contentshasha you read the file at, from GET /pages/{path}/content or a previous save. Omit it for a new file, or to overwrite without a check.messagedocs: update <path>, or docs: update N files (…) for several.publishfalseResponse — 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.
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.