---
title: "Create a build from a source archive, repository, or managed source"
method: POST
path: "/v1/spaces/{spaceId}/builds"
tags: ["Builds"]
---

# Create a build from a source archive, repository, or managed source

`POST /v1/spaces/{spaceId}/builds`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/spaces/{spaceId}/builds`
- Auth: HTTP bearer

Creates a build that produces a version on success through the normal publish path. Repository inputs use the saved connection; source archive inputs receive an upload instruction the new build owns. Naming a managed `source` instead builds it from its connected production repository with the saved settings and live target. The caller cannot select source code, commands, settings, refs, or publish targets, and must send an `Idempotency-Key` header: a managed-source trigger without one fails with 422 `idempotency_key_required`.

## Path parameters

- `spaceId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- union: A caller-described build, or a build triggered from a managed source.
  - object: Trigger a production build for a Space's configured WordPress source.
    - `source` 'wordpress', required: Build the Space's configured WordPress source.
    - `sourceUrl` string, uri, required: Configured WordPress URL that changed, as stored in the Space's data sources.
  - object
    - `input` union, required: What a new build should run against.
      - object
        - `kind` 'archive', required: Build from an uploaded source archive.
        - `sourceMetadata` object: Source provenance for the produced version.
      - object
        - `kind` 'repository', required: Build from a repository connection.
        - `repositoryConnectionId` string, required: Repository connection (`rpc_`) to build from.
        - `ref` string: Branch, tag, or ref to build.
        - `commit` string: Exact commit built, once resolved.
        - `branch` string: Branch name when the ref is a commit SHA.
    - `settings` object: Per-run settings overrides, persisted as `settingsSnapshot` after resolution.
      - `rootDirectory` string, nullable
      - `installDirectory` string, nullable
      - `installCommand` string, nullable
      - `buildCommand` string, nullable
      - `outputDirectory` string, nullable
      - `ignoredBuildCommand` string, nullable
      - `frameworkPreset` string, nullable
      - `platformPreset` string, nullable
      - `allowUnsupportedPlatformFeatures` boolean
      - `timeoutSeconds` integer
    - `target` object: Omit to use the Space's channel mapping for the repository ref. Send channel: null or preview: true to prevent automatic promotion. An empty target object also prevents promotion.
      - `channel` string, nullable: Channel to promote when the build succeeds. production is an alias for live; null means no automatic promotion.
      - `preview` boolean: Whether the build targets preview behavior.
    - `diagnostics` object[]: Diagnostics already known before the build is queued.
      - `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.
    - `wait` boolean: Wait for the build to finish before this request returns. Agents must keep this false and poll the build status. Synchronous clients can set it to true.

## 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

- `201`: Response for status 201
- `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)