Skip to main content
GET
/
api
/
projects
/
:id
/
builds
Project Builds
curl --request GET \
  --url https://api.example.com/api/projects/:id/builds
{
  "success": true,
  "total": 123,
  "builds": [
    {
      "_id": "<string>",
      "commitSha": {},
      "status": "<string>",
      "startedAt": {},
      "finishedAt": {},
      "logUrl": {},
      "createdAt": "<string>"
    }
  ],
  "build": {
    "_id": "<string>",
    "commitSha": {},
    "status": "<string>",
    "startedAt": {},
    "finishedAt": {},
    "logUrl": {},
    "dockerImage": {},
    "createdAt": "<string>"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.deployhub.cloud/llms.txt

Use this file to discover all available pages before exploring further.

​
List Project Builds

​
id
string
required
The unique identifier of the project (MongoDB ObjectId)

​
Authentication

Requires JWT authentication via the verifyJWT middleware.

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
total
number
required
Total number of builds for this project. Returns totalBuilds from project document if available, otherwise returns the count of builds in the response.
​
builds
array
required
Array of build objects, sorted by creation date (newest first), limited to 50 most recent builds

​
Example Request

curl -X GET "https://api.deployhub.online/api/projects/65f3a2b1c4d5e6f7g8h9i0j1/builds" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Example Response

{
  "success": true,
  "total": 23,
  "builds": [
    {
      "_id": "65f5d3e4f5g6h7i8j9k0l1m2",
      "commitSha": "a3f7d9e2c1b4f6e8d0c2a5b7",
      "status": "success",
      "startedAt": "2024-03-20T14:20:15.000Z",
      "finishedAt": "2024-03-20T14:22:03.000Z",
      "logUrl": "https://logs.deployhub.online/builds/65f5d3e4f5g6h7i8j9k0l1m2.log",
      "createdAt": "2024-03-20T14:20:10.000Z"
    },
    {
      "_id": "65f5c2d3e4f5g6h7i8j9k0l1",
      "commitSha": "b2e8f1a3d5c7e9f0a2b4c6d8",
      "status": "failed",
      "startedAt": "2024-03-19T09:15:30.000Z",
      "finishedAt": "2024-03-19T09:16:45.000Z",
      "logUrl": "https://logs.deployhub.online/builds/65f5c2d3e4f5g6h7i8j9k0l1.log",
      "createdAt": "2024-03-19T09:15:25.000Z"
    },
    {
      "_id": "65f5b1c2d3e4f5g6h7i8j9k0",
      "commitSha": "c3f9e2a4d6c8e0f1a3b5c7d9",
      "status": "pending",
      "createdAt": "2024-03-18T16:45:00.000Z"
    }
  ]
}

​
Get Build by ID

Retrieve detailed information about a specific build.

​
Path Parameters

​
id
string
required
The unique identifier of the project (MongoDB ObjectId)
​
buildId
string
required
The unique identifier of the build (MongoDB ObjectId)

​
Response

​
success
boolean
required
Indicates whether the request was successful
​
build
object
required
Detailed build information

​
Example Request

curl -X GET "https://api.deployhub.online/api/projects/65f3a2b1c4d5e6f7g8h9i0j1/builds/65f5d3e4f5g6h7i8j9k0l1m2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Example Response

{
  "success": true,
  "build": {
    "_id": "65f5d3e4f5g6h7i8j9k0l1m2",
    "commitSha": "a3f7d9e2c1b4f6e8d0c2a5b7",
    "status": "success",
    "startedAt": "2024-03-20T14:20:15.000Z",
    "finishedAt": "2024-03-20T14:22:03.000Z",
    "logUrl": "https://logs.deployhub.online/builds/65f5d3e4f5g6h7i8j9k0l1m2.log",
    "dockerImage": "deployhub/65f3a2b1c4d5e6f7g8h9i0j1:a3f7d9e",
    "createdAt": "2024-03-20T14:20:10.000Z"
  }
}

​
Error Responses

​
404 Not Found - Project
Returned when the project doesn’t exist, doesn’t belong to the user, or has been deleted
{
  "success": false,
  "message": "Project not found"
}
​
404 Not Found - Build
Returned when the build doesn’t exist or doesn’t belong to the specified project
{
  "success": false,
  "message": "Build not found"
}
​
500 Internal Server Error
Returned when a server error occurs
{
  "success": false,
  "message": "Server error"
}

​
Implementation Notes

​
List Builds

  • Returns up to 50 most recent builds
  • Builds are sorted by createdAt in descending order (newest first)
  • Only selects relevant fields to minimize response size
  • Verifies project ownership before returning builds
  • Uses .lean() for optimized read-only queries

​
Get Build by ID

  • Verifies that the build belongs to the specified project
  • Verifies project ownership through the project lookup
  • Includes dockerImage field which is not returned in the list endpoint
  • Returns additional build metadata for debugging and analysis

​
Build Status Flow

  1. pending - Build is created and queued
  2. success or failed - Build completes with final status
  3. startedAt is set when build processing begins
  4. finishedAt is set when build completes (success or failure)
  • To trigger a new build, use the redeploy endpoint: POST /api/redeploy/:projectId
  • Build logs can be accessed via the logUrl field
  • The most recent build is also included in the project overview endpoint

​
Source Reference

  • List builds: backend/src/controllers/slices/Project/Buildscontroller.js:4
  • Get build by ID: backend/src/controllers/slices/Project/Buildscontroller.js:32
  • Build model: backend/src/models/slices/build.model.js:3