Refresh a build's upload target

Returns the build with a fresh upload target when the previous one expired before the archive was sent. A target that is still valid comes back unchanged. Only a build still waiting for source qualifies: an upload that already completed fails with 409 build_source_upload_already_completed.

POST/v1/builds/{buildId}/uploads/refresh

Authorization

Authorization Bearer token · header required

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

Path parameters

buildId string 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

Properties

build object required

• id string required

Build ID (`bld_` prefix). Opaque, and never derived from a version ID.

• spaceId string required

Space (`spc_` prefix) the build publishes into.

• status string required

Where the build is in its lifecycle. `skipped` means the ignored build command decided no build was needed.

Allowed: waiting_for_source, uploading_source, queued, running, succeeded, failed, canceled, skipped

• input object required

The source a build ran against, with clone URLs and repository connection identifiers removed.

One of:

• kind string required

The build ran against an uploaded source archive.

• kind string required

The build ran against repository source.

• ref string

Branch, tag, or ref the build checked out.

• commit string

Commit the ref resolved to. Absent until resolved.

• branch string

Branch the ref belongs to, when it is known.

• pullRequestNumber integer

Pull request the build was raised for. Absent for builds off a plain branch.

max 9007199254740991

• source object

Publish provenance as declared when the build started: client, git ref data, and publish message. It is present on running and failed builds, which have no version yet; once a version exists its own `source` is authoritative. Null when nothing was declared.

default: null

Any of:

• kind string required

How this version was produced. `variable_update` and `config_update` mark republishes Spacefast makes on its own when a variable or a setting changed; the rest name what published.

Allowed: direct_upload, cli, dashboard, api, git, import, agent, build, variable_update, config_update

• client string

Client and version that published, for example `spacefast-cli/1.2.3`.

max length 255

• branch string

Git branch the publish was made from.

max length 255

• commit string

Git commit the publish was made from.

max length 64

• message string

One-line description of the publish, shown as the version's headline in the dashboard. There is no separate changelog field. The CLI fills it from the git commit message when it can.

max length 2000

• dirty boolean

Whether the working tree had uncommitted changes when the publish was made.

• metadata object

Extra provenance as string pairs, such as a repository, a CI run URL, a workflow, or an actor.

• git object

Properties

• repository string | any

• repositoryFullName string | any

• repositoryUrl string | any

• ref string | any

• branch string | any

• branchAliasUrl string | any

• commit string | any

• commitSha string | any

• pullRequestNumber number | any

• settingsSnapshot object required

Build settings after saved values and per-run overrides are merged. A build freezes these at creation and runs against them for its whole life.

• rootDirectory string | any required

Directory the build runs in, relative to the source root. Null builds at the root.

default: null

• installDirectory string | any required

Directory dependencies install into, relative to the source root. Null installs in the build directory.

default: null

• installCommand string | any required

Command that installs dependencies. Null lets the build runner pick one.

default: null

• buildCommand string | any required

Command that produces the output. Null lets the build runner pick one.

default: null

• outputDirectory string | any required

Directory the built output is collected from, relative to the build directory. Null lets the build runner detect it.

default: null

• ignoredBuildCommand string | any required

Command run before the build to decide whether the build is needed. Exiting 0 ends the build as `skipped`; any other exit code continues. Null always builds.

default: null

• frameworkPreset string | any required

Framework the source builds with, for example `next` or `vite`. Null lets the build runner detect it.

default: null

• platformPreset string | any required

Platform build convention the source follows, for example `vercel` or `netlify`. Null lets the build runner detect it.

default: null

• allowUnsupportedPlatformFeatures boolean required

Runs the build even when the source declares platform features Spacefast does not support. Defaults to `false`, which refuses those sources.

default: false

• timeoutSeconds integer required

Wall-clock budget for the run, in seconds. Between 60 and 7200; defaults to 900.

min 60 · max 7200 · default: 900

• target object required

Where a successful build's version goes.

Properties

• channel string | any required

Channel the produced version is promoted to when the build succeeds. Null publishes the version without promoting it.

default: null

• 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.

default: false

• retryOfBuildId string | any required

Build this run retries. Null when it is not a retry.

default: null

• 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.

default: null

• diagnostics object[] required

default: []

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.

• provider string | any

Upstream system that raised the diagnostic. Absent when Spacefast raised it.

• details object | any

Machine-readable context keyed by the diagnostic code.

• fix string | any

What to change to clear the diagnostic. Absent when there is no known fix.

• retryable boolean | any

True when repeating the same operation unchanged can clear the diagnostic.

• createdAt string required

ISO 8601 timestamp when the build was created.

• startedAt string | any required

ISO 8601 timestamp when the build runner started the run. Null until it does.

• finishedAt string | any required

ISO 8601 timestamp when the build reached a terminal state. Null while it is still in flight.

• upload object | any required

default: null

Any of:

• 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. Clients that skip it upload `targets` one by one instead.

• kind string required

• method string required

• url string | string required

Runtime endpoint that accepts one ZIP whose entries are named by their digest.

• headers object required

Headers to send verbatim with the ZIP, including the upload authorization.

default: {}

• maxCompressedBytes integer required

Largest ZIP this endpoint accepts, in bytes.

max 9007199254740991

• maxExpandedBytes integer required

Largest total size the ZIP may expand to, in bytes.

max 9007199254740991

• maxBlobs integer required

Most entries one ZIP may carry.

max 9007199254740991

• details object

Diagnostics

• diagnostics object[]

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.

• provider string | any

Upstream system that raised the diagnostic. Absent when Spacefast raised it.

• details object | any

Machine-readable context keyed by the diagnostic code.

• fix string | any

What to change to clear the diagnostic. Absent when there is no known fix.

• retryable boolean | any

True when repeating the same operation unchanged can clear the diagnostic.

Reused

• reused object[]

Array of object

• path string required

• reason string required

• expiresAt string required

ISO 8601 timestamp when the authorization in `headers` stops working. Only the credential lapses; the version stays open, and `links.refresh` mints a fresh page with a new one.

IDs

• id string required

Upload session ID (`upl_` prefix).

min length 1

• links object required

Show propertiesHide properties

• refresh string required

Endpoint that mints a fresh instruction page for whatever the session still needs, with a new authorization. Call it after uploading this page's targets.

• resume string

• finalize string required

Endpoint that commits the version once every declared file has landed.

Summary

• summary object required

Counts across the whole manifest, not only the targets on this page.

• reused integer required

Files satisfied by bytes the Space already holds under the same digest.

min 0 · max 9007199254740991

• upload integer required

Files whose bytes are still needed.

min 0 · max 9007199254740991

Targets

• targets object[] required

Targets to upload on this page, capped by a per-page limit. Upload these, then call `links.refresh` for whatever the session still needs.

default: []

Array of object

• path string required

Manifest path whose bytes this target accepts.

• method string required

Method to send the upload with.

Allowed: PUT, POST

• url string | string required

Where to send the bytes. Absolute, or relative to the API origin.

• headers object required

Headers to send verbatim, including the upload authorization. Adding or dropping any of them fails the upload.

default: {}

• body object

How to fill the request body. Absent means send the local bytes for `path`. `url` means POST this JSON so the runtime fetches the file itself.

Example Requests

• curl

curl -X POST "https://api.spacefast.com/v1/builds/string/uploads/refresh" \
  -H "Authorization: Bearer YOUR_TOKEN"

• JavaScript

const response = await fetch("https://api.spacefast.com/v1/builds/string/uploads/refresh", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

• Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/builds/string/uploads/refresh",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "$schema": "http://example.com",
  "data": {
    "build": {
      "id": "string",
      "spaceId": "string",
      "status": "waiting_for_source",
      "input": {
        "kind": "archive"
      },
      "source": null,
      "settingsSnapshot": {
        "rootDirectory": null,
        "installDirectory": null,
        "installCommand": null,
        "buildCommand": null,
        "outputDirectory": null,
        "ignoredBuildCommand": null,
        "frameworkPreset": null,
        "platformPreset": null,
        "allowUnsupportedPlatformFeatures": false,
        "timeoutSeconds": 900
      },
      "target": {
        "channel": null,
        "preview": false
      },
      "retryOfBuildId": null,
      "producedVersionId": "string",
      "reusedVersionId": null,
      "diagnostics": [],
      "createdAt": "2019-08-24T14:15:22Z",
      "startedAt": "2019-08-24T14:15:22Z",
      "finishedAt": "2019-08-24T14:15:22Z"
    },
    "upload": null
  }
}

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}