Skip to content
SupaCloud Docs
Select themeSelect language

`POST /api/apps/{id}/builds` -- enqueue a build of the App's current source for the WebIde live-preview (ADR 0030 UX3-A). Idempotent on the source hash: an unchanged source returns the existing (possibly succeeded) build. Returns the build row so the client can start polling immediately.

POST
/api/apps/{id}/builds
curl --request POST \
  --url https://example.com/api/apps/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/builds

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

One build of an App’s source folder (ADR 0030 W3-1). The status column is stored as TEXT (matching every other status-bearing row in this codebase, e.g. AppDeployment / Run); use [AppBuildStatus] to parse / format it in a typed way. claimed_by is the runner id that took the build off the queue (no FK – runners are not a workspace-scoped table).

object
app_id
required
string format: uuid
artifact_sha

SHA of the produced artifact, set once status = 'succeeded'.

string | null
claimed_at
string | null format: date-time
claimed_by

Runner id that claimed the build off the queue. None while queued.

string | null format: uuid
completed_at
string | null format: date-time
created_at
required
string format: date-time
error_message

Populated when status = 'failed'.

string | null
id
required
string format: uuid
source_sha256
required

Content hash over the App’s source folder. UNIQUE per App, so a re-build of identical source resolves to the existing row instead of enqueueing.

string
status
required
string
wall_clock_secs

End-to-end build duration in whole seconds, stamped on completion.

integer | null format: int32
workspace_id
required
string format: uuid
Examplegenerated
{
  "app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "artifact_sha": "example",
  "claimed_at": "2026-04-15T12:00:00Z",
  "claimed_by": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "completed_at": "2026-04-15T12:00:00Z",
  "created_at": "2026-04-15T12:00:00Z",
  "error_message": "example",
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "source_sha256": "example",
  "status": "example",
  "wall_clock_secs": 1,
  "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}