Builds

Trigger and monitor Docker image builds for your Release applications.

Base URL: https://api.release.com

---

List Builds

Retrieve a paginated list of builds for a given app.

Endpoint

GET /apps/{appId}/builds

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app

Pagination

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	25	Results per page

Status Codes

Status	Description
200	Successfully retrieved builds
401	Unauthorized — invalid or missing authentication headers
404	App not found

Example Responses

200 OK

{
  "total_count": 48,
  "items": [
    {
      "id": "xk9m2v",
      "aasm_state": "done",
      "branch": "main",
      "commit_short": "a1b2c3d",
      "total_duration": 182.5,
      "started_at": "2025-06-01T12:00:00Z"
    },
    {
      "id": "pl3n8w",
      "aasm_state": "running",
      "branch": "feature/auth",
      "commit_short": "e4f5g6h",
      "total_duration": null,
      "started_at": "2025-06-01T12:30:00Z"
    }
  ]
}

---

Trigger Build

Trigger a new build for a specific app.

Endpoint

POST /apps/{appId}/builds

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app

Status Codes

Status	Description
201	Build successfully triggered
401	Unauthorized — invalid or missing authentication headers
404	App not found

Example Responses

201 Created

{
  "id": "rm4k7q",
  "aasm_state": "queued",
  "branch": "main",
  "commit_short": "b2c3d4e",
  "total_duration": null,
  "started_at": null
}

---

Get Build

Retrieve details for a specific build.

Endpoint

GET /apps/{appId}/builds/{buildId}

Authentication

Authenticate using headers from your ~/.release.yaml file. To set this up, install the Release CLI and run release auth login.

Header	Description
X-User-Email	User email from ~/.release.yaml (login field)
X-User-Token	User token from ~/.release.yaml (token field)

Headers

Header	Value	Required
Accept	application/json	Yes

Path Parameters

Parameter	Type	Required	Description
appId	string (hashid)	Yes	The unique identifier of the app
buildId	string (hashid)	Yes	The unique identifier of the build

Status Codes

Status	Description
200	Successfully retrieved build
401	Unauthorized — invalid or missing authentication headers
404	Build not found

Response Body

Field	Type	Description
id	string (hashid)	Build identifier
aasm_state	string	One of: queued, running, done, errored
branch	string	Branch name for the build
commit_short	string	Abbreviated commit SHA
total_duration	number or null	Duration in seconds
started_at	string (ISO 8601) or null	When the build started

Example Responses

200 OK

{
  "id": "xk9m2v",
  "aasm_state": "done",
  "branch": "main",
  "commit_short": "a1b2c3d",
  "total_duration": 182.5,
  "started_at": "2025-06-01T12:00:00Z"
}

---

State Lifecycle

queued → running → done | errored

State	Description
queued	Build is queued and waiting to start
running	Build is currently executing
done	Build completed successfully
errored	Build failed with errors