/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Deploy Source Files

Deploy Source Files

Upload documentation source files to build and deploy, as stx deploy does.

POST/v1/projects/{projectId}/deployTry it
API key or session token

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.

Note

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

NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).

Request Body

Send multipart/form-data.

NameDescription
files:filebodyRequired
A source file. Repeat the field once per file. At least one is required.
paths:stringbody
The relative path of each file, e.g. docs/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.
preview:stringbody
true for a preview deployment. Otherwise the upload deploys to production, on branch main.
Default"false"
branch:stringbody
Branch name for a preview, used in its URL. Ignored for production. A preview with no branch, or with main, 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.
export:stringbody
true 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.
Default"false"

Response

Returns 202 Accepted. Follow the build with Get Build or the logsUrl log stream.

NameDescription
data.buildId:string
The new build.
data.status:string
Always queued.
data.branch:string
The branch the build was recorded on: main for production and exports, else the preview branch.
data.isPreview:boolean
Whether this is a preview deployment.
data.isExport:boolean
Whether this is an export build.
data.fileCount:integer
Number of files received.
data.logsUrl:string
Path of the build's log stream.
data.contentSource:string
Where the project's content lives: upload (deployed with stx deploy), github or hosted (written in Syntext).
warnings:array
Top level, next to data, 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.queuedBehind:object | null
The build this one is waiting on. Builds of one project run one at a time, so an upload that lands while another build of the project is running — typically the GitHub webhook's build of the latest merge — waits as queued 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.
Show 8 child attributesobject | null
Note

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

Statuserror.codeWhen
400bad_requestNo files were uploaded
400invalid_pathA file path would leave the upload (see paths). details.path names it; nothing is stored or built
401unauthorizedNo credential, or an invalid, revoked or expired one
402USAGE_LIMIT_EXCEEDEDThe workspace has used its monthly build quota. Nothing is uploaded
403forbiddenYou are not a member of the project's workspace, or the API key's scope is below build
404not_foundThe project does not exist or is deleted, or the API key belongs to another project
409build_cancelledThe build was cancelled while its files uploaded. details.buildId names it

409 Conflict

json
{
"error": {
"code": "build_cancelled",
"message": "The build was cancelled while its files were uploading.",
"details": {
"buildId": "bld_new123",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

402 Payment Required

See Usage limit errors.

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Monthly build limit reached (100/100). Upgrade your plan for more builds.",
"current": 100,
"limit": 100,
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/deploy \
-H "Authorization: Bearer stx_abc12345_..." \
-F "files=@syntext.json" -F "paths=syntext.json" \
-F "files=@docs/quickstart.mdx" -F "paths=docs/quickstart.mdx" \
-F "preview=true" \
-F "branch=feature/new-api"
Responseapplication/json
202Accepted
{
"data": {
"buildId": "bld_new123",
"status": "queued",
"branch": "feature/new-api",
"isPreview": true,
"isExport": false,
"fileCount": 2,
"logsUrl": "/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds/bld_new123/logs/stream",
"queuedBehind": null,
"contentSource": "upload"
}
}
Responseapplication/json
202Accepted, behind another build
{
"data": {
"buildId": "bld_new456",
"status": "queued",
"branch": "main",
"isPreview": false,
"isExport": false,
"fileCount": 42,
"logsUrl": "/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds/bld_new456/logs/stream",
"queuedBehind": {
"buildId": "bld_web789",
"status": "compiling",
"trigger": "github_app",
"branch": "main",
"commitSha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
"isPreview": false,
"createdAt": "2026-11-13T09:58:12Z",
"startedAt": "2026-11-13T09:58:14Z"
},
"contentSource": "github"
}
}
Responseapplication/json
200OK
{
"data.buildId": "string",
"data.status": "string",
"data.branch": "string",
"data.isPreview": true,
"data.isExport": true,
"data.fileCount": 0,
"data.logsUrl": "string",
"data.contentSource": "string",
"warnings": [],
"data.queuedBehind": {
"buildId": "string",
"status": "string",
"trigger": "string",
"branch": "string",
"commitSha": "string",
"isPreview": true,
"createdAt": "string",
"startedAt": "string"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext