On this page
Build image on a build
Builds an image, with an SBOM and signed provenance, from a commit or an uploaded tree.
This method is not served on the public API.
api.sylphx.comdoes not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.
Builds an image, with an SBOM and signed provenance, from a commit or an uploaded tree.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/builds:buildImage - Scope
build:run - Effect
write— a successful call changes state. - Collection builds
- Validate-only
validate_only=trueruns every check and writes nothing - Operation answers with an
Operation; the result isBuild
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The project to build in. Required. |
source | BuildSource | A commit, read through the Broker at that exact commit. One of the input group. |
tree | BuildTree | An uploaded tree. One of the input group. |
image | ImageTarget | The image to build. |
size | BuildSize | The machine size; default [build] size, else STANDARD. One of standard, large, xlarge. |
timeout | duration | The time limit; default 1 hour. |
allow_hosts | string[] | Internet hosts the build may reach; empty means in-cell only. |
cache | string | The BuildCache to use; default the project's default cache. |
build_id | string | The id segment of the Build's name; the server assigns one when unset. |
validate_only | bool | Validate and return the result without writing anything. |
BuildSource
| Field | Type | What it is |
|---|---|---|
source_link | string | The Hosting SourceLink naming the repository and its Connection. Required. |
commit | string | The full commit SHA to build. Required. |
root_directory | string | The directory inside the repository to build; default the root. |
BuildTree
| Field | Type | What it is |
|---|---|---|
root_digest | string | The root Directory digest, <sha256 hex>/<size in bytes>. Required. |
ImageTarget
| Field | Type | What it is |
|---|---|---|
service | string | The sylphx.toml service whose dockerfile and context apply; unset reads the fields below or lets the zero-config frontend detect the stack. |
dockerfile | string | A Dockerfile path relative to the input root; unset lets the zero-config frontend detect the stack. |
target | string | The Dockerfile stage to build. |
build_args | map<string, string> | Build arguments. Secret values bind through [build.secrets], never here. |
Response
| Field | Type | What it is |
|---|---|---|
name | string | {parent-of-target}/operations/{operation}. |
target | string | The name of the Resource being changed. |
target_generation | int64 | The generation this Operation waits for. |
verb | OperationVerb | What the Operation does. One of create, update, delete, custom. |
custom_verb | string | The custom method verb when verb is CUSTOM, for example revoke. |
done | bool | Whether the Operation has finished. |
create_time | timestamp | When the Operation started. |
end_time | timestamp | When the Operation finished. |
response | any | The settled Resource (or Empty for a delete). One of the result group. |
error | ProblemDetails | The failure, as the one error body. One of the result group. |
progress | OperationProgress | Progress while not done. |
ProblemDetails
| Field | Type | What it is |
|---|---|---|
type | string | https://sylphx.com/docs/errors/<code in kebab-case>. |
title | string | A short customer-safe summary of the problem class. |
status | int32 | The HTTP status, fixed by grpc_status. |
detail | string | A customer-safe explanation of this occurrence. Never contains SQL, stack traces, internal hostnames, or another tenant's data. |
instance | string | The request id (Sylphx-Request-Id). |
code | string | The stable UPPER_SNAKE code, one of ErrorCode without its prefix. |
grpc_status | string | One of the 16 canonical gRPC status names, for example ABORTED. |
retryable | bool | Whether the same request may be retried. |
effect | ErrorEffect | What the failed call committed. One of none, applied, unknown. |
retry_after_ms | int64 | How long to wait before retrying, when the server knows. |
details | any[] | Typed details such as PreconditionFailure or EntitlementDenial. |
OperationProgress
| Field | Type | What it is |
|---|---|---|
percent | int32 | Percent complete, when the controller can tell. |
message | string | A customer-safe progress message. |
conditions | Condition[] | The target's conditions when this progress was read. |
Condition
| Field | Type | What it is |
|---|---|---|
type | string | The condition type, for example Ready. |
status | ConditionStatus | Whether the condition holds. One of true, false, unknown. |
observed_generation | int64 | The generation this observation was made against. |
reason | string | A machine-readable UpperCamelCase reason. |
message | string | A customer-safe human-readable message. |
severity | Severity | How severe a FALSE condition is. One of info, warning, error. |
transition_time | timestamp | When status last changed. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.UNKNOWN_FIELD— The request has a field the schema does not know.INVALID_FIELD— A field failed validation.RESOURCE_ALREADY_EXISTS— A Resource with this name exists.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.PLAN_LIMIT_REACHED— The plan's limit is reached.SPEND_LIMIT_REACHED— The org's spend limit is reached.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/builds:buildImage" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'