Deploy Source Files
Upload documentation source files to build and deploy, as stx deploy does.
Upload a project's documentation source — MDX, Markdown, syntext.json, images — for the server to compile and deploy. This is the endpoint behind stx deploy. Use it when the docs do not live in a connected repository.
Any workspace member (session JWT), or an API key bound to this project with the build scope or higher. Any plan — each upload counts as a build toward the monthly build quota, and returns 402 USAGE_LIMIT_EXCEEDED once it is used up.
The build is created with status uploading, then moves to queued once the files are stored. If the build is cancelled while the files upload, the request returns 409 build_cancelled and nothing is queued. The build's trigger is cli_upload and triggeredByUserId is you (or null for an API key).
Path Parameters
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Request Body
Send multipart/form-data.
filespathsdocs/quickstart.mdx. Repeat it once per file, in the same order as files. When a path is missing, the file's name is used. Paths must stay inside the upload: no leading /, drive letter, . or .. segment, empty segment or control character, at most 512 characters, and not _manifest.json. Backslashes are read as /. The whole upload is refused (400 invalid_path) if any path breaks these rules.previewtrue for a preview deployment. Otherwise the upload deploys to production, on branch main."false"branchmain, uses preview. If <branch>--<subdomain> would be longer than 63 characters, the branch part of the hostname is shortened and ends in a 6-character code.exporttrue to compile a downloadable site bundle instead of publishing, as stx build does. Download it from GET /v1/projects/{projectId}/builds/{buildId}/export once the build is deployed. An export is never a preview and is always a full rebuild."false"Response
Returns 202 Accepted. Follow the build with Get Build or the logsUrl log stream.
data.buildIddata.statusqueued.data.branchmain for production and exports, else the preview branch.data.isPreviewdata.isExportdata.fileCountdata.logsUrldata.contentSourceupload (deployed with stx deploy), github or hosted (written in Syntext).warningsdata, and present only when there is something to say. On a project written in Syntext it holds { "code": "hosted_content_diverges", "message": … }: this deploy publishes the uploaded files, the pages stored in Syntext are unchanged, and they replace the upload at the next publish from the dashboard. When the upload has _syntext/head.html or _syntext/*.js and the caller isn't a workspace admin or owner (or a full-access API key one of them created), it holds { "code": "custom_code_not_applied", … }: the deploy goes ahead without them — see Deploys from the CLI.data.queuedBehindqueued until it finishes. This is the project's running build, or else the oldest build queued ahead of this one; null when nothing is ahead. Keep following the build with Get Build, which reports the same field while the build is queued.buildIdstatusqueued, cloning, parsing, compiling or deploying.triggerbranchcommitShanull for uploaded files.isPreviewcreatedAtstartedAtnull while it is still queued.A production upload never puts older content back live. If a production build of the project that was requested later has already deployed by the time this one would publish, this build stops without publishing and ends as cancelled, with error set to Superseded: build <id> was requested later and is already live, so this build did not publish. Previews and exports are never superseded.
Response — 202 Accepted, behind another build
A production upload made while the webhook build of a merge is still compiling:
Error Responses
| Status | error.code | When |
|---|---|---|
| 400 | bad_request | No files were uploaded |
| 400 | invalid_path | A file path would leave the upload (see paths). details.path names it; nothing is stored or built |
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 402 | USAGE_LIMIT_EXCEEDED | The workspace has used its monthly build quota. Nothing is uploaded |
| 403 | forbidden | You are not a member of the project's workspace, or the API key's scope is below build |
| 404 | not_found | The project does not exist or is deleted, or the API key belongs to another project |
| 409 | build_cancelled | The build was cancelled while its files uploaded. details.buildId names it |
409 Conflict
402 Payment Required
See Usage limit errors.