/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Trigger Build

Trigger Build

Queue a new build of a project's repository.

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

Queue a build of the project's connected repository — for example after a configuration change, or to build one exact commit.

Note

Any workspace member (session JWT), or an API key bound to this project with the build scope or higher. Any plan — each build counts toward the workspace's monthly build quota, and the request returns 402 USAGE_LIMIT_EXCEEDED once it is used up.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID, a UUID.

Request Body

All fields are optional. Send {} to build the production branch head.

NameDescription
branch:stringbody
Branch to build. Defaults to the project's repoBranch, else main. Any branch other than the production branch (repoBranch) is built as a preview — including main when the production branch is something else. Only when no repoBranch is set do both main and master build as production.
commitSha:stringbody
A commit to check out and build, 7–40 hexadecimal characters. Stored lowercased. A full sha is fetched directly. A short sha needs the repository history, so it takes longer. A commit that is not in the repository fails the build with an error starting Commit a1b2c3d was not found in the repository. A production build only builds commits that are on the production branch: any other commit fails with Commit a1b2c3d is not on the production branch main. Production builds use only commits from it: merge the change first, or build that branch as a preview. Defaults to the head of branch.
force:booleanbody
Rebuild even when the source is unchanged since the last build.
Defaultfalse

Response

Returns 201 Created with the new build object (without triggeredBy). status is queued. triggeredByUserId is your user id for a session JWT, and null for an API key.

The build runs asynchronously. Poll Get Build or read its log to follow it, or cancel it.

Projects written in Syntext or deployed with stx deploy

How the request behaves depends on where the project's content lives:

•
Written in Syntext (hosted content): the build publishes the pages stored in Syntext, the same as Publish in the editor. branch, commitSha and force are ignored, and the build's trigger is editor. It can also fail with 409 nothing_to_publish (no pages yet), 413 content_too_large, 503 storage_unavailable or 409 build_cancelled (cancelled while its files were uploading).
•
Deployed with stx deploy (upload): nothing is stored to build from, so the request returns 409 content_source_upload. Run stx deploy instead.

Error Responses

Statuserror.codeWhen
400—The body is invalid, e.g. commitSha is not 7–40 hex characters. See below
401unauthorizedNo credential, or an invalid, revoked or expired one
402USAGE_LIMIT_EXCEEDEDThe workspace has used its monthly build quota
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

400 Bad Request

validation_error — the body failed validation. details.issues lists each problem:

json
{
"error": {
"code": "validation_error",
"message": "commitSha: commitSha must be 7 to 40 hex characters",
"details": {
"issues": [
{ "path": ["commitSha"], "code": "invalid_string", "message": "commitSha must be 7 to 40 hex characters" }
],
"target": "json",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

402 Payment Required

The monthly build quota is used up. Do not retry until the quota resets or the workspace upgrades — 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
}
}
Was this page helpful? Yes No
Previous
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/builds \
-H "Authorization: Bearer stx_abc12345_..." \
-H "Content-Type: application/json" \
-d '{
"branch": "main",
"commitSha": "a1b2c3d",
"force": true
}'
Responseapplication/json
201Created
{
"data": {
"id": "bld_new123",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"priority": 0,
"status": "queued",
"trigger": "manual",
"commitSha": "a1b2c3d",
"commitMessage": null,
"filesChanged": null,
"branch": "main",
"isPreview": false,
"deployUrl": null,
"error": null,
"logs": [],
"pageCount": null,
"durationMs": null,
"contentHash": null,
"sourcePath": null,
"deployId": null,
"warnings": 0,
"degraded": [],
"triggeredByUserId": null,
"createdAt": "2026-11-08T12:00:00Z",
"startedAt": null,
"completedAt": null
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext