Create a build

Creates a build for the Space and returns it, with an upload target when the input needs one. An archive input starts the build waiting for source and hands back the target to send the archive to; a repository input resolves the saved connection and queues the build straight away. Naming a managed source instead of an input builds the Space’s configured WordPress source from its connected production repository, at the saved settings and the live channel, and requires an Idempotency-Key header: without one the call fails with 422 idempotency_key_required. Repeating an Idempotency-Key returns the build that key already created with 200 rather than 201, and reusing it for a different body fails with 409 idempotency_key_reused. A successful build mints a version through the same publish path as any other publish.

POST /v1/spaces/{spaceId}/builds

Authorization

Authorization Bearer token · header required

Authorization: Bearer <token> with an API key (sfa_ prefix), an OAuth access token, a session token, or a Space machine credential (sfm_ prefix).

Path parameters

• spaceId: string required

Header parameters

• Idempotency-Key: string

Client-generated key, up to 255 characters, that makes this write safe to retry. The first request with a key stores its outcome, scoped to the tenant, credential, method, and path. A retry with the same key and body replays the stored response with Idempotency-Replayed: true. A different body with the same key fails with 409 idempotency_key_reused. A retry while the first request is still running fails with 409 idempotency_conflict_in_progress. Keys are kept for 24 hours.

max length 255

Request body

required application/json

Either a build described with input, or a managed source that decides what to build.

One of:

• object

  • source: string required
    • Builds the Space's configured WordPress source instead of a caller-described input.
  • sourceUrl: string required
    • WordPress URL whose content changed. It must match a WordPress data source configured on the Space.
    • min length 1 · max length 2048 · matches ^https://[^/?#@%\s]+(?:/[^?#\s]*)?$

• object

  • diagnostics: object[]
    • Diagnostics the caller already collected, recorded on the build before it runs.

Show properties

Array of object

• code: string required
  • Stable snake_case code for this diagnostic.
• severity: string required
  • How serious the diagnostic is.
  • Allowed: info warning error
• message: string required
  • What happened, in a sentence a person can act on.
• path: string | any
  • File or artifact path the diagnostic refers to, with a line number when known, for example _headers:12. Absent when it applies to the whole resource.

Any of:

• string

input: object required

What a new build runs against.

One of:

• object
  • kind: string required
    • Build a source archive uploaded to the target this call hands back.
    • sourceMetadata: object
      • Publish provenance to record on the build and on the version it produces, for example the client, branch, commit, and publish message.

object

• kind: string required
  • Build a repository connection saved on the Space.
  • repositoryConnectionId: string required
    • Repository connection (rpc_ prefix) to build from.
  • ref: string
    • Branch, tag, or ref to build. Defaults to the connection's production branch, then its default branch.
  • commit: string
    • Commit the ref resolved to. Absent until resolved.
  • branch: string
    • Branch the ref belongs to, when the ref is a commit.
  • settings: object
    • Settings to change for this run. The merged result is frozen on the build as settingsSnapshot.

Show properties

rootDirectory, installDirectory, installCommand, buildCommand, outputDirectory, ignoredBuildCommand,

frameworkPreset, platformPreset

allowUnsupportedPlatformFeatures: boolean

timeoutSeconds: integer min 60 · max 7200

target: object required

Where a successful build's version goes.

• channel: string | any required
• Channel the produced version is promoted to when the build succeeds. Null publishes the version without promoting it.
• preview: boolean required
• Marks the run as a preview build. The build environment is exported as a preview, and a preview build only supersedes other preview builds on the same branch.
• retryOfBuildId: string | any required
• Build this run retries. Null when it is not a retry.
• producedVersionId: string | any required
• Version (ver_ prefix) this build minted. Null until a build succeeds and mints one.
• reusedVersionId: string | any required
• Version the build reused because the output was unchanged. Null otherwise.
• diagnostics: object[] required
• default: []

Array of object

• code: string required
• severity: string required
• message: string required
• path: string | any
• provider: string | any
• details: object | any
• fix: string | any
• retryable: boolean | any

createdAt, startedAt, finishedAt

• createdAt: string required
• startedAt: string | any required
• finishedAt: string | any required

upload: object | any required

• bulk: object - One request that carries this page's targets as a single ZIP. Present only when every target on the page is content-addressed.
• kind: string required
• method: string required
• url: string | string required
• headers: object required
• maxCompressedBytes: integer required
• maxExpandedBytes: integer required
• maxBlobs: integer required

responses

200 Response for status 200

• $schema: string
  • 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
• id: string required
• spaceId: string required
• status: string required
• input: object required

Try it

cURL Example

curl -X POST "https://api.spacefast.com/v1/spaces/string/builds" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "wordpress",
  "sourceUrl": "http://example.com"
}'

JavaScript Example

const response = await fetch("https://api.spacefast.com/v1/spaces/string/builds", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"source\": \"wordpress\",\n  \"sourceUrl\": \"http://example.com\"\n}"
});

Python Example

import requests

response = requests.post(
    "https://api.spacefast.com/v1/spaces/string/builds",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"source\": \"wordpress\",\n  \"sourceUrl\": \"http://example.com\"\n}",
)