Skip to main content
A build record is created automatically when you push to a connected branch or create a new project. These two endpoints let you interact with builds directly: re-run any build using its original commit hash, and fetch the current state of a specific build. Both endpoints verify that the build’s project belongs to the authenticated user before responding.

​
POST /api/build/rebuild/:buildId

Re-runs the build pipeline using the commit hash recorded on an existing build. A new build record is inserted with status: "queued" and the pipeline starts immediately in the background. The original build record is not modified. Requires JWT. The rebuild copies the original build’s commit, branch, commitAuthor, commitHash, and projectId into the new record. This means a rebuild is always tied to the same snapshot of the repository — it does not re-fetch the latest commit.

​
Path parameters

​
buildId
number
required
Numeric ID of the existing build to re-run. Build IDs are returned in the builds array of GET /api/project/projects.

​
Curl example

curl -X POST https://your-server/api/build/rebuild/14 \
  -H "Authorization: Bearer <your-jwt>"

​
Response

The server responds immediately with the new build record. The actual pipeline runs asynchronously after the response is sent. 
{
  "message": "Build re-queued",
  "build": {
    "id": 22,
    "status": "queued",
    "commit": "fix: update hero copy",
    "branch": "main",
    "commitAuthor": "Jane Doe",
    "commitHash": "a1b2c3d4e5f6",
    "exitCode": null,
    "projectId": 7,
    "startedAt": "2026-04-11T14:00:00.000Z",
    "finishedAt": null
  }
}

​
Response fields

​
build
object
The newly created build record.
​
build.id
number
Unique ID of the new build. Use this to poll GET /api/build/:buildId or subscribe to buildStatusUpdate Socket.io events.
​
build.status
string
Initial status. Always queued immediately after creation.
​
build.commitHash
string
The commit hash that will be checked out for this build — identical to the original build’s hash.
​
build.exitCode
number | null
null until the build completes. On completion, 0 means the build passed; any non-zero value means it failed.
Rebuild runs asynchronously. Monitor progress in real time by subscribing to the buildStatusUpdate Socket.io event, filtering by the new build’s id. The event is emitted each time the build status changes (queued → running → passed/failed).

​
Error responses

StatusCondition
400buildId or user ID is missing
401JWT is missing or invalid
403The build’s project does not belong to the authenticated user
404No build found with the given ID
500Failed to insert the new build record

​
GET /api/build/:buildId

Fetches a single build record by ID, including the nested project details. Use this to check a build’s final status and exit code after it completes, or to retrieve a snapshot of a build’s metadata. Requires JWT.

​
Path parameters

​
buildId
number
required
Numeric ID of the build to fetch.

​
Curl example

curl https://your-server/api/build/14 \
  -H "Authorization: Bearer <your-jwt>"

​
Response

{
  "message": "Build fetched",
  "build": {
    "id": 14,
    "status": "passed",
    "commit": "fix: update hero copy",
    "branch": "main",
    "commitAuthor": "Jane Doe",
    "commitHash": "a1b2c3d4e5f6",
    "exitCode": 0,
    "projectId": 7,
    "startedAt": "2026-04-11T12:00:05.000Z",
    "finishedAt": "2026-04-11T12:02:30.000Z",
    "project": {
      "id": 7,
      "name": "my-vite-app",
      "repoUrl": "https://github.com/acme-corp/my-vite-app",
      "branch": "main"
    }
  }
}

​
Response fields

​
build
object
The build record.
​
build.id
number
Unique build ID.
​
build.status
string
Current build status. One of queued, running, passed, or failed.
ValueMeaning
queuedBuild is waiting to start
runningBuild pipeline is actively executing
passedBuild completed successfully
failedBuild exited with an error
​
build.commit
string
The commit message from the triggering push.
​
build.branch
string
Branch the build was triggered on.
​
build.commitAuthor
string
Name of the commit author as reported by GitHub.
​
build.commitHash
string
Full SHA of the commit that was checked out for this build.
​
build.exitCode
number | null
Exit code of the build container. null while the build is running. 0 on success; any other value indicates a failure.
​
build.projectId
number
ID of the project this build belongs to.
​
build.startedAt
string
ISO 8601 timestamp of when the build record was created.
​
build.finishedAt
string | null
ISO 8601 timestamp of when the build completed. null while running.

​
Error responses

StatusCondition
400buildId or user ID is missing
401JWT is missing or invalid
403The build’s project does not belong to the authenticated user
404No build found with the given ID

Build docs developers (and LLMs) love

Get started for freeTalk to us