Project Builds

curl --request GET \
  --url https://api.example.com/api/projects/:id/builds

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/projects/:id/builds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/projects/:id/builds"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/projects/:id/builds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

GET

api

projects

:id

builds

Project Builds

curl --request GET \
  --url https://api.example.com/api/projects/:id/builds

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/projects/:id/builds",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/projects/:id/builds"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/projects/:id/builds")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

List Project Builds

string

required

The unique identifier of the project (MongoDB ObjectId)

Authentication

Requires JWT authentication via the verifyJWT middleware.

Response

boolean

required

Indicates whether the request was successful

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.

array

required

Array of build objects, sorted by creation date (newest first), limited to 50 most recent builds

Show Build object fields

string

Build unique identifier (MongoDB ObjectId)

string | undefined

Git commit SHA that triggered this build

string

Current build status

pending - Build is queued and waiting to start
success - Build completed successfully
failed - Build failed

string | undefined

ISO 8601 timestamp when the build started

string | undefined

ISO 8601 timestamp when the build finished

string | undefined

URL to the build logs

string

ISO 8601 timestamp when the build was created

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

string

required

The unique identifier of the project (MongoDB ObjectId)

string

required

The unique identifier of the build (MongoDB ObjectId)

Response

boolean

required

Indicates whether the request was successful

object

required

Detailed build information

Show Build fields

string

Build unique identifier

string | undefined

Git commit SHA that triggered this build

string

Build status: pending, success, or failed

string | undefined

ISO 8601 timestamp when the build started

string | undefined

ISO 8601 timestamp when the build finished

string | undefined

URL to the complete build logs

string | undefined

Docker image identifier created by this build

string

ISO 8601 timestamp when the build was created

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

Returned when the project doesn’t exist, doesn’t belong to the user, or has been deleted

{
  "success": false,
  "message": "Project not found"
}

Returned when the build doesn’t exist or doesn’t belong to the specified project

{
  "success": false,
  "message": "Build not found"
}

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

pending - Build is created and queued
success or failed - Build completes with final status
startedAt is set when build processing begins
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

Authentication

Deployments

Projects

User Management

Subscriptions

Project Builds

List Project Builds

Authentication

Response

Example Request

Example Response

Get Build by ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Implementation Notes

List Builds

Get Build by ID

Build Status Flow

Source Reference

​List Project Builds

​Authentication

​Response

​Example Request

​Example Response

​Get Build by ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

​Implementation Notes

​List Builds

​Get Build by ID

​Build Status Flow

​Related Endpoints

​Source Reference

List Project Builds

Authentication

Response

Example Request

Example Response

Get Build by ID

Path Parameters

Response

Example Request

Example Response

Error Responses

Implementation Notes

List Builds

Get Build by ID

Build Status Flow

Related Endpoints

Source Reference