Menu
Platform
AI
App store purchases
Credits
Database
Flags
Generated Assets
Jobs and cron
Localization
Monitoring
Notifications
Payments
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Run a build
Runs one command over an uploaded tree and settles with its exit code, like the local command.
Runs one command over an uploaded tree and settles with its exit code, like the local command. A caller that gets a failure before the command started (BUILD_FAILURE_SETUP_FAILED, NO_CAPACITY) may build locally.
Not available yet. Sylphx Build is declared in the registry but no backend serves it: every call answers 501 with the problem code UNIMPLEMENTED.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/builds:run - 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 run in. Required. |
tree | BuildTree | The uploaded tree to run over. Required. |
command | string[] | The program and its arguments. Required. |
artifacts | string[] | Globs of files kept after the command ends, whatever its exit code. |
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 command 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. |
#BuildTree
| Field | Type | What it is |
|---|---|---|
root_digest | string | The root Directory digest, <sha256 hex>/<size in bytes>. Required. |
#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:run" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":["…"],"tree":{"root_digest":"…"}}'