Template builds

Request a custom template build (queued for the isolated builder)

202 with the queued build. Takes recipe v1 (a Dockerfile) or recipe v2 (: validated against the base, compiled to the builder’s steps, uploads locked). Records the canonical recipe and its SHA-256 (provenance input), pins the base version, clamps resources to the plan and assigns target_version. The cell executes it (building -> testing -> publishing -> published) and the API then registers the version (published at once unless auto_publish=false); poll GET .../template-builds/{id} until registration.state is registered (or the build failed/was canceled). builder_availability says whether a builder is running. Errors: 422 when the recipe is outside the host builder Dockerfile dialect or the slug is not a builder slug (details.reason: multi_stage_not_supported, from_not_template_base, stage_names_not_supported, from_flags_not_supported, base_mismatch, run_flags_not_supported, heredoc_not_supported, instruction_not_supported, no_build_context, env_invalid, user_invalid, too_many_steps, recipe_too_large, slug_not_supported_by_builder, platform_template_slug, reserved_template_slug, base_not_found, base_not_published, base_archived, architecture_not_supported, ...; line for line errors; recipe v2: invalid_recipe (details.field, details.detail), base_not_layered, language_unavailable, language_conflict, invalid_package, too_many_files, platform_owned_path, invalid_path, upload_required, upload_missing, upload_digest_mismatch, upload_too_large, too_many_steps, recipe_too_large, allowlist_empty, allow_hosts_without_allowlist, extra_hosts_without_auto, too_many_hosts, invalid_host, ip_literal_not_allowed, host_not_allowed, invalid_settings, services_unsupported, too_many_acknowledged_findings; immutable paths: invalid_path (details.field recipe.immutable[<i>]), immutable_path_removed (the recipe drops a path of the template’s open version; details.removed), immutable_paths_unsupported_base (a non-empty list on a base whose guest agent lacks immutable_paths.v1, or a recipe v1 build of a template with immutable paths; details.base {name, version})), 503 dependency_unavailable (uploads_not_configured), 402 entitlement_required, 429 rate_limited (template_build_queue_full: already 10 builds queued past the plan’s concurrent_template_builds; retryable, Retry-After; a build past the plan’s slots is accepted and waits, its queue gives the position and expected wait), 409 template_archived. Supports Idempotency-Key.

post/v1/organizations/{organization_id}/template-builds

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/organizations/{organization_id}/template-builds
  • Auth: HTTP bearer

Path parameters

organization_idstring uuid required

UUIDv7, lowercase canonical form.

Request body

template_slugstring required

Organization template to build into (created by the first build). Platform slugs and the reserved slugs new and edit are refused for new templates.

auto_publishboolean

Publish the produced version as soon as it is registered (new workspaces of the slug then use it). false: it stays unpublished until an owner/admin publishes it.

display_namestring

Template name when this build creates the template.

descriptionstring

The version description (manifest description).

acknowledged_scan_findingsstring[]

Recipe v2 only: up to 200 absolute paths the credential scan may report without failing the build (recorded in the manifest).

Response

Default Response

idstring uuid required

UUIDv7, lowercase canonical form.

organization_idstring uuid required

UUIDv7, lowercase canonical form.

state'queued' | 'building' | 'testing' | 'publishing' | 'published' | 'succeeded' | 'failed' | 'canceled' required

queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see registration) | failed | canceled. succeeded = legacy builds.

target_versioninteger nullable required

Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds.

auto_publishboolean required

Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route.

published_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

cancel_requested_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

created_atstring date-time required

RFC 3339 UTC timestamp with Z.

updated_atstring date-time required

RFC 3339 UTC timestamp with Z.

started_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

completed_atstring date-time nullable required

RFC 3339 UTC timestamp with Z.

architecturestring required
denied_hostsstring[] required

Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it.

publishableboolean required
source_kind'recipe' | 'workspace' required

recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish).

source_workspace_idstring uuid nullable required

UUIDv7, lowercase canonical form.

source_checkpoint_idstring nullable required

The saved checkpoint (filled when the capture finished and the cell claimed the build).

scrub_resultobject nullable required

sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents.

filesobject nullable required

The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes}).

produced_layer_idstring uuid nullable required

UUIDv7, lowercase canonical form.

squashedboolean nullable required

The base chain already had 4 org layers: this build squashed them into its one layer.

org_bytesinteger nullable required

The produced chain’s org bytes (limited by the plan’s workspace disk limit).

immutable_pathsstring[] required

The immutable paths the produced version declares, in byte order: the recipe’s immutable, else the list of the template’s open version (a save from a workspace: the target template’s open version’s list, else the workspace’s version’s). Empty for none.

Changes

No recorded changes to this operation across all 1 revision of this API.