POST/v1/projects/{projectId}/builds

Trigger Build

Manually trigger a new build for a project. Useful for rebuilding after configuration changes or debugging.

Path Parameters

The project ID (e.g., prj_abc123).

Request Body

Branch to build. Defaults to the project's configured branch.

Deploy as a preview build instead of production.

Specific commit SHA to build. Defaults to HEAD of the branch.

Force rebuild even if no changes detected.

Response

Returns the created build object with status: "queued".

Example

curl -X POST https://api.syntext.dev/v1/projects/prj_abc123/builds \
-H "Authorization: Bearer stx_abc12345_..." \
-H "Content-Type: application/json" \
-d '{
"branch": "main",
"force": true
}'

import { Syntext } from '@syntext/sdk'

const client = new Syntext('stx_abc12345_...')

const build = await client.builds.trigger('prj_abc123', {
branch: 'main',
force: true,
})

from syntext import Syntext

client = Syntext("stx_abc12345_...")

build = client.builds.trigger(
"prj_abc123",
branch="main",
force=True,
)

Response

{
  "data": {
    "id": "bld_new123",
    "status": "queued",
    "trigger": "api",
    "branch": "main",
    "commitSha": "a1b2c3d4e5f6",
    "isPreview": false,
    "createdAt": "2026-06-28T12:00:00Z"
  }
}

The build is queued immediately and processed asynchronously. Poll the Get Build endpoint or use webhooks to track progress.

Error Responses

404 Not Found

Returned when the project does not exist.

{
  "error": {
    "code": "not_found",
    "message": "Project does not exist"
  }
}

400 Bad Request

Returned when the request is invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid branch or commit SHA"
  }
}

409 Conflict

Returned when a build is already in progress.

{
  "error": {
    "code": "conflict",
    "message": "A build is already in progress"
  }
}

429 Too Many Requests

Returned when you've triggered too many builds recently.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many builds triggered recently. Try again later."
  }
}