Builds API

List Builds

Get all builds for a deployment:

GET /api/v1/deployments/{deployment_id}/builds
Authorization: Bearer <token>

Response:

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "deployment_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "commit_sha": "abc123def456789",
    "image_tag": "registry:5000/myapp:abc123de",
    "started_at": "2024-01-25T10:00:00Z",
    "finished_at": "2024-01-25T10:02:30Z"
  },
  {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "deployment_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "commit_sha": "def456ghi789012",
    "image_tag": null,
    "started_at": "2024-01-24T14:00:00Z",
    "finished_at": "2024-01-24T14:01:15Z"
  }
]

Get Build

GET /api/v1/deployments/{deployment_id}/builds/{build_id}
Authorization: Bearer <token>

Response:

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "deployment_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "commit_sha": "abc123def456789",
  "image_tag": "registry:5000/myapp:abc123de",
  "started_at": "2024-01-25T10:00:00Z",
  "finished_at": "2024-01-25T10:02:30Z"
}

Get Build Logs

GET /api/v1/deployments/{deployment_id}/builds/{build_id}/logs
Authorization: Bearer <token>

Response:

Step 1/8 : FROM node:20-alpine
 ---> 1a2b3c4d5e6f
Step 2/8 : WORKDIR /app
 ---> Running in abc123def456
 ---> 7g8h9i0j1k2l
Step 3/8 : COPY package*.json ./
 ---> 3m4n5o6p7q8r
Step 4/8 : RUN npm ci
 ---> Running in rst123uvw456

added 150 packages in 12s

Step 5/8 : COPY . .
 ---> 4s5t6u7v8w9x
Step 6/8 : RUN npm run build
 ---> Running in xyz123abc456

> myapp@1.0.0 build
> tsc && vite build

vite v5.0.0 building for production...
✓ 42 modules transformed.
dist/index.html    0.42 kB │ gzip: 0.27 kB
dist/assets/index-abc123.js  142.30 kB │ gzip: 45.12 kB

Step 7/8 : EXPOSE 3000
 ---> 5a6b7c8d9e0f
Step 8/8 : CMD ["node", "dist/server.js"]
 ---> 6g7h8i9j0k1l

Successfully built xyz789abc012
Successfully tagged registry:5000/myapp:abc123de

Build Status Values

Status	Description
`pending`	Build queued
`building`	Build in progress
`success`	Build completed successfully
`failed`	Build failed
`cancelled`	Build was cancelled

Build Metadata

commit_sha

For git deployments, this is the Git commit SHA:

Full 40-character hash
Used to identify the exact code version

For archive deployments, this is the archive hash:

SHA256 of the uploaded archive
Ensures reproducibility

image_tag

The full Docker image tag:

registry:5000/{subdomain}:{short_hash}

Used for:

Running the container
Rollbacks
Image management

Stream Build Logs (WebSocket)

For real-time build logs during a build:

const ws = new WebSocket(
  'wss://api.domain.com/api/v1/deployments/{id}/builds/{build_id}/logs/stream'
);

ws.onmessage = (event) => {
  console.log(event.data);
};

The WebSocket sends log lines as they’re produced during the build.

Error Responses

Build Not Found

HTTP/1.1 404 Not Found

{
  "error": "not_found",
  "message": "Build not found"
}

Logs Not Available

HTTP/1.1 404 Not Found

{
  "error": "not_found",
  "message": "Build logs not available"
}

Logs may be unavailable if:

The build is still pending
Logs have been cleaned up
The build was cancelled before logging started