---
title: Trigger Build
protocol: rest
method: POST
endpoint: /v1/projects/{projectId}/builds
description: "Manually trigger a new build"
---

# Trigger Build

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

<Endpoint method="POST" path="/v1/projects/{projectId}/builds" />

## Path Parameters

<ParamField path="projectId" type="string" required>
  The project ID (e.g., `prj_abc123`).
</ParamField>

## Request Body

<ParamField body="branch" type="string">
  Branch to build. Defaults to the project's configured branch.
</ParamField>

<ParamField body="isPreview" type="boolean" default="false">
  Deploy as a preview build instead of production.
</ParamField>

<ParamField body="commitSha" type="string">
  Specific commit SHA to build. Defaults to HEAD of the branch.
</ParamField>

<ParamField body="force" type="boolean" default="false">
  Force rebuild even if no changes detected.
</ParamField>

## Response

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

## Example

<CodeGroup>
```bash cURL
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
  }'
```

```typescript SDK
import { Syntext } from '@syntext/sdk'

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

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

```python Python
from syntext import Syntext

client = Syntext("stx_abc12345_...")

build = client.builds.trigger(
    "prj_abc123",
    branch="main",
    force=True,
)
```
</CodeGroup>

### Response

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

<Note>
The build is queued immediately and processed asynchronously. Poll the [Get Build](/api-reference/builds/get) endpoint or use webhooks to track progress.
</Note>

## Error Responses

### 404 Not Found

Returned when the project does not exist.

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

### 400 Bad Request

Returned when the request is invalid.

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

### 409 Conflict

Returned when a build is already in progress.

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

### 429 Too Many Requests

Returned when you've triggered too many builds recently.

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