Build endpoints — trigger and fetch builds

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

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

object

The newly created build record.

number

Unique ID of the new build. Use this to poll GET /api/build/:buildId or subscribe to buildStatusUpdate Socket.io events.

string

Initial status. Always queued immediately after creation.

string

The commit hash that will be checked out for this build — identical to the original build’s hash.

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

Status	Condition
`400`	`buildId` or user ID is missing
`401`	JWT is missing or invalid
`403`	The build’s project does not belong to the authenticated user
`404`	No build found with the given ID
`500`	Failed 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

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

object

The build record.

number

Unique build ID.

string

Current build status. One of queued, running, passed, or failed.

Value	Meaning
`queued`	Build is waiting to start
`running`	Build pipeline is actively executing
`passed`	Build completed successfully
`failed`	Build exited with an error

string

The commit message from the triggering push.

string

Branch the build was triggered on.

string

Name of the commit author as reported by GitHub.

string

Full SHA of the commit that was checked out for this build.

number | null

Exit code of the build container. null while the build is running. 0 on success; any other value indicates a failure.

number

ID of the project this build belongs to.

string

ISO 8601 timestamp of when the build record was created.

string | null

ISO 8601 timestamp of when the build completed. null while running.

Error responses

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

Overview

Endpoints

Build endpoints — trigger and fetch builds

POST /api/build/rebuild/:buildId

Path parameters

Curl example

Response

Response fields

Error responses

GET /api/build/:buildId

Path parameters

Curl example

Response

Response fields

Error responses

​POST /api/build/rebuild/:buildId

​Path parameters

​Curl example

​Response

​Response fields

​Error responses

​GET /api/build/:buildId

​Path parameters

​Curl example

​Response

​Response fields

​Error responses

POST /api/build/rebuild/:buildId

Path parameters

Curl example

Response

Response fields

Error responses

GET /api/build/:buildId

Path parameters

Curl example

Response

Response fields

Error responses