Trigger Build
Queue a new build of a project's repository.
Queue a build of the project's connected repository — for example after a configuration change, or to build one exact commit.
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
projectIdRequest Body
All fields are optional. Send {} to build the production branch head.
branchrepoBranch, 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.commitShaCommit 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.forcefalseResponse
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:
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).stx deploy (upload): nothing is stored to build from, so the request returns 409 content_source_upload. Run stx deploy instead.Error Responses
| Status | error.code | When |
|---|---|---|
| 400 | — | The body is invalid, e.g. commitSha is not 7–40 hex characters. See below |
| 401 | unauthorized | No credential, or an invalid, revoked or expired one |
| 402 | USAGE_LIMIT_EXCEEDED | The workspace has used its monthly build quota |
| 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 |
400 Bad Request
validation_error — the body failed validation. details.issues lists each problem:
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.