# 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 <uri> 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<date-time> required
- **startedAt**: string<date-time> | any required
- **finishedAt**: string<date-time> | 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<uri> | string required
- `headers`: object required
- `maxCompressedBytes`: integer required
- `maxExpandedBytes`: integer required
- `maxBlobs`: integer required

### responses

200 Response for status 200
- **$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
- **id**: string required
- **spaceId**: string required
- **status**: string required  
- **input**: object required

## Try it
### cURL Example
```bash
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
```javascript
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
```python
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}",
)
```