--- title: "Retry a build with the original immutable input and settings" method: POST path: "/v1/builds/{buildId}/retry" tags: ["Builds"] --- # Retry a build with the original immutable input and settings `POST /v1/builds/{buildId}/retry` ## Request - Base URL: `https://api.spacefast.com` - URL: `https://api.spacefast.com/v1/builds/{buildId}/retry` - Auth: HTTP bearer Creates a new build from the original immutable input and settings snapshot, then queues it for execution or returns a fresh source archive upload instruction when needed. ## Path parameters - `buildId` string, required ## Response `200` Response for status 200 - object - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header. - `data` object, required - `build` object, required - `capture` object: URL capture progress and advisory evidence; absent for other inputs. - `state` string, required - `previewSummary` object - `progress` object - `archiveHash` string - `id` string, required: Build id (`bld_`); opaque and never derived from a version id. - `spaceId` string, required: Space (`spc_`) the build produces a version for. - `status` 'waiting_for_source' | 'uploading_source' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'skipped', required: Build lifecycle status. - `input` union, required: Public build input. Internal clone URLs and provider source references are hidden. - object - `kind` 'url', required - `sourceUrl` string, uri, required - object - `kind` 'archive', required: Build from an uploaded source archive. - object - `kind` 'repository', required: Build from repository source where clone credentials are not exposed. - `ref` string, required: Branch, tag, or ref to build. - `commit` string: Exact commit built, once resolved. - `branch` string: Branch name when available. - `pullRequestNumber` integer - `source` object, nullable, required: Publish provenance as declared at build start (client, git ref data, publish message). Present on failed and running builds too; the produced version's `source` is the authoritative copy once one exists. Null when nothing was declared. - `kind` 'direct_upload' | 'cli' | 'dashboard' | 'api' | 'git' | 'import' | 'agent' | 'build' | 'variable_update' | 'config_update', required: How this version was produced. - `client` string: Publishing client attribution, for example `spacefast-cli/1.2.3`. - `branch` string: Git branch the publish came from. - `commit` string: Git commit SHA the publish came from. - `message` string: Plain-language description of the publish (the version changelog entry, commit message, or release note). This is THE spelling for the publish description; the version files-diff API is the fallback when none is given. - `dirty` boolean: Whether the working tree had uncommitted changes at publish time. - `metadata` object: Additional provenance (repository, CI run URL, workflow, actor, ...). - `git` object - `repository` string, nullable - `repositoryFullName` string, nullable - `repositoryUrl` string, nullable - `ref` string, nullable - `branch` string, nullable - `branchAliasUrl` string, nullable - `commit` string, nullable - `commitSha` string, nullable - `pullRequestNumber` number, nullable - `settingsSnapshot` object, required: Resolved build settings. Builds persist this as an immutable `settingsSnapshot`. - `rootDirectory` string, nullable, required - `installDirectory` string, nullable, required - `installCommand` string, nullable, required - `buildCommand` string, nullable, required - `outputDirectory` string, nullable, required - `ignoredBuildCommand` string, nullable, required - `frameworkPreset` string, nullable, required - `platformPreset` string, nullable, required - `allowUnsupportedPlatformFeatures` boolean, required - `timeoutSeconds` integer, required - `target` object, required: Where a successful build should publish or run in preview mode. - `channel` string, nullable, required: Channel to promote when the build succeeds. production is an alias for live; null means no automatic promotion. - `preview` boolean, required: Whether the build targets preview behavior. - `retryOfBuildId` string, nullable, required: Original build retried by this build. - `producedVersionId` string, nullable, required: Version (`ver_`) minted by a successful build; null otherwise. - `reusedVersionId` string, nullable, required: Existing version reused by a successful no-change build; null otherwise. - `diagnostics` object[], required - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it. - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is. - `message` string, required: Human-readable explanation with enough detail to act on. - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists. - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself. - `details` object, nullable: Machine-readable context for the diagnostic code. - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived. - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything. - `createdAt` string, date-time, required - `startedAt` string, date-time, nullable, required: When the runner picked the build up. - `finishedAt` string, date-time, nullable, required: When the build reached a terminal state. - `upload` object, nullable, required - `id` string, required: Upload session id (upl_…) minted by the runtime. - `mode` 'dist' | 'source', required: `dist` bytes are publishable output. `source` bytes must be transformed, unpacked, or built before publish. - `expiresAt` string, date-time, required: Instant when the session token expires. This rotates only the token, never the version lifecycle boundary. Resume always mints a fresh token. - `summary` object, required: Counts for the whole manifest, independent of target paging. - `upload` integer, required: Files that still need uploading. - `reused` integer, required: Files satisfied by hash reuse. - `ignored` integer: Deprecated; current servers return zero. - `targets` object[], required: Opaque upload targets, bounded by the instruction payload budget. Upload these, then call `links.refresh` for the remainder. - `path` string, required: Caller-local path/key identifying the bytes this target accepts. - `method` 'PUT' | 'POST', required: HTTP method to use for this target. - `url` union, required: Absolute or API-relative upload URL issued by the control plane. - string, uri - string - `headers` object, required: Exact headers to send with the upload request. - `body` object: Optional body recipe. Omitted means the client uploads the local bytes for `path`; `url` means POST the URL for server-side fetch. - `kind` 'url', required - `url` string, uri, required - `size` integer: Expected byte size when known. - `maxBytes` integer: Maximum accepted byte size when the server can advertise it. - `sha256` string - `contentType` string - `bulk` object: Optional direct runtime transport for this page's content-addressed targets. Clients that do not support it continue with targets. - `kind` 'zip-cas-v1', required - `method` 'PUT', required - `url` union, required: Upload-auth runtime URL that accepts a ZIP of SHA-named CAS blobs. - string, uri - string - `headers` object, required: Exact headers to send with the bulk upload request. - `maxCompressedBytes` integer, required - `maxExpandedBytes` integer, required - `maxBlobs` integer, required - `links` object, required - `refresh` string, required - `resume` string - `finalize` string, required - `details` object - `reused` object[] - `path` string, required - `reason` string, required - `diagnostics` object[] - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it. - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is. - `message` string, required: Human-readable explanation with enough detail to act on. - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists. - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself. - `details` object, nullable: Machine-readable context for the diagnostic code. - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived. - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything. ## Other responses - `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document. --- [API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)