Skip to content
Console
On this page

List builds

Lists builds in a project.

Lists builds in a project.

  • Path GET https://api.sylphx.com/v1/orgs/acme/projects/shop/builds
  • Scope build:read
  • Effect read — nothing is written.
  • Collection builds
  • Query page_size, page_token, filter, order_by
  • Pagination the answer carries builds and, when there is more, next_page_token

Request

FieldTypeWhat it is
parentstringThe parent to list in. Required.
page_sizeint32At most this many; default 50, clamped to 1000.
page_tokenstringnext_page_token of the previous page.
filterstringAIP-160 filter over labels, filterable fields, and Ready.
order_bystringAIP-132 ordering over filterable fields.

Response

FieldTypeWhat it is
buildsBuild[]The page.
next_page_tokenstringThe token of the next page; empty on the last page.

Build

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/builds/{build}.
uidstringbld_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
specBuildSpecDesired state. Required.
statusBuildStatusObserved state. Output only.

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

BuildSpec

FieldTypeWhat it is
sourceBuildSourceA commit, read through the Broker at that exact commit. One of the input group.
cachestringThe BuildCache to read and write; default the project's default cache.
treeBuildTreeA tree uploaded to the org's store, by its root digest. One of the input group.
imageImageTargetAn OCI image with an SBOM and signed provenance. One of the output group.
commandCommandTargetOne command's exit code and the artifacts it names. One of the output group.
sizeBuildSizeThe machine size; default [build] size, else STANDARD. One of standard, large, xlarge.
timeoutdurationThe time limit; default 1 hour, at most 6 hours. A command that reaches it is killed and the Build ends with BUILD_FAILURE_TIMEOUT.
allow_hostsstring[]Internet hosts the build may reach. Empty means in-cell only: the mirrors and the store. Default [build] allow_hosts.

BuildStatus

FieldTypeWhat it is
observed_generationint64The generation this status was computed from. Output only.
conditionsCondition[]Ready, Reconciling, Stalled. Output only.
stateBuildStateThe lifecycle state. Output only. One of queued, running, succeeded, failed, cancelled.
failureBuildFailureWhy the build failed, when state is FAILED. Output only. One of source_unavailable, build_error, no_capacity, class_not_offered, signing_unavailable, timeout, setup_failed.
outputBuildOutputThe result: an image when state is SUCCEEDED; for a command, set whenever the command ran, whatever its exit code. Output only.
leasestringThe Sandboxes lease the build ran on. Output only.
start_timetimestampWhen the build started running. Output only.
end_timetimestampWhen the build reached a final state. Output only.
log_uristringWhere the build log is read, through Observability. Output only.
workspaceBuildWorkspaceWhether the build took a warm workspace of the same repository. Output only. One of warm, cold.
bytes_upint64Bytes the client uploaded for this build: the blobs of the tree the org's store lacked. Output only.

BuildSource

FieldTypeWhat it is
source_linkstringThe Hosting SourceLink naming the repository and its Connection. Required.
commitstringThe full commit SHA to build. Required.
root_directorystringThe directory inside the repository to build; default the root.

BuildTree

FieldTypeWhat it is
root_digeststringThe root Directory digest, <sha256 hex>/<size in bytes>. Required.

ImageTarget

FieldTypeWhat it is
servicestringThe sylphx.toml service whose dockerfile and context apply; unset reads the fields below or lets the zero-config frontend detect the stack.
dockerfilestringA Dockerfile path relative to the input root; unset lets the zero-config frontend detect the stack.
targetstringThe Dockerfile stage to build.
build_argsmap<string, string>Build arguments. Secret values bind through [build.secrets], never here.

CommandTarget

FieldTypeWhat it is
argvstring[]The program and its arguments. Use ["bash", "-lc", "…"] for a shell. Required.
artifactsstring[]Globs, relative to the input root, of files kept after the command ends, whatever its exit code (test reports, coverage).

Condition

FieldTypeWhat it is
typestringThe condition type, for example Ready.
statusConditionStatusWhether the condition holds. One of true, false, unknown.
observed_generationint64The generation this observation was made against.
reasonstringA machine-readable UpperCamelCase reason.
messagestringA customer-safe human-readable message.
severitySeverityHow severe a FALSE condition is. One of info, warning, error.
transition_timetimestampWhen status last changed.

BuildOutput

FieldTypeWhat it is
imagestringThe image reference: registry.sylphx.net/<path>@sha256:<hex>. Output only.
image_digeststringThe image manifest digest. Output only.
sbom_digeststringThe SBOM Artifact digest. Output only.
provenance_digeststringThe signed SLSA provenance Artifact digest. Output only.
artifactstringThe artifact in Sylphx Artifacts that holds the three. Output only.
exit_codeint32The command's own exit code. Output only.
artifactsBuildArtifact[]The files the command's artifacts globs matched, by digest. Output only.

Errors

Every error arrives in the body Errors describes.

Examples

curl "https://api.sylphx.com/v1/orgs/acme/projects/shop/builds" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"