Set a space variable

Creates or updates a space variable by name. The new value applies when a version next finalizes; the live version keeps its sealed values.

PUT/v1/spaces/{spaceId}/variables/{name}

Authorization

AuthorizationBearer token · headerrequired

Space key (sfc_…) for an unclaimed anonymous Space. Also the fragment of its claim URL and the token of its /__/<key> door.

AuthorizationBearer token · headerrequired

Better Auth session, OAuth access token, OAuth client-credentials token, or sfm_ Space machine credential.

AuthorizationOAuth2 access token · headerrequired

OAuth 2.0 with explicit Spacefast capability scopes. Use the authorization-code flow for people and client credentials for machines.

Scopes:spaces:write

Path parameters

spaceIdstringrequired

namestringrequired

Request body

requiredapplication/json

valuestringrequired

min length 1

secretbooleanrequired

Whether the value is write-only.

channelValuesobject

Responses

200Response for status 200

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

dataobjectrequired

Show properties

namestringrequired

Variable name, referenced as {{ vars.NAME }} in templates.

min length 1 · max length 128 · matches ^[A-Za-z_][A-Za-z0-9_]*$

scopestringrequired

Where the variable is defined; space wins over principal.

Allowed:spaceprincipal

secretbooleanrequired

Secret values are write-only and never returned after creation.

valuestring

Variable value; omitted when secret=true.

channelValuesobject

Per-channel overrides compiled into channel template variants; omitted for secrets.

createdAtstring<date-time>required

Instant when the variable was created.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updatedAtstring<date-time>required

Instant when the value was last written.

operationobject | anyrequired

The debounced re-finalize cascade this write coalesced into; null when no cascade was required.

Show properties

Any of:

object

idstringrequired

kindstringrequired

statusstringrequired

Allowed:queuedrunningsucceededfailedcanceled

resourcesobject[]required

Show properties

Array of object

typestringrequired

idstringrequired

progressobject

Show properties

totalintegerrequired

min 0 · max 9007199254740991

completedintegerrequired

min 0 · max 9007199254740991

failedintegerrequired

min 0 · max 9007199254740991

diagnosticsobject[]

Show properties

Array of object

codestringrequired

Stable snake_case diagnostic code naming the public contract that produced it.

severitystringrequired

How actionable the diagnostic is.

Allowed:infowarningerror

messagestringrequired

Human-readable explanation with enough detail to act on.

pathstring | any

Artifact path the diagnostic points at, for example "_headers:12", when one exists.

Show properties

Any of:

string

string

any

any

providerstring | any

Upstream system the diagnostic originated from, when not Spacefast itself.

Show properties

Any of:

string

string

any

any

detailsobject | any

Machine-readable context for the diagnostic code.

Show properties

Any of:

object

object

any

any

fixstring | any

Concrete, agent-actionable remediation hint, when one can be derived.

Show properties

Any of:

string

string

any

any

retryableboolean | any

Whether retrying the same operation can resolve this diagnostic without the caller changing anything.

Show properties

Any of:

boolean

boolean

any

any

createdAtstring<date-time>required

finishedAtstring<date-time>

any

any

defaultProblem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

typestringrequired

Problem type URI resolving to the error docs page. The server derives it mechanically from `code` against the docs origin.

titlestringrequired

Short human-readable summary of the problem type. The server derives it mechanically from `code`.

statusintegerrequired

HTTP status code of this response, repeated in the body.

min -9007199254740991 · max 9007199254740991

detailstringrequired

Human-readable failure explanation for this occurrence.

codestringrequired

Stable snake_case error code naming the failed public contract.

pointerstring

RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.

detailsobject

Machine-readable context for the error code.

suggestionsstring[]

Actionable recovery steps safe to show in dashboards, SDKs, and CLI output.

nextstring[]

Copy-pasteable commands or API requests an agent can run next.

requestIdstringrequired

The request id to quote when contacting support.

Request

curl -X PUT "https://api.spacefast.com/v1/spaces/string/variables/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "string",
  "secret": true,
  "channelValues": {
    "property1": "string",
    "property2": "string"
  }
}'

const response = await fetch("https://api.spacefast.com/v1/spaces/string/variables/string", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "value": "string",
  "secret": true,
  "channelValues": {
    "property1": "string",
    "property2": "string"
  }
})
});

import requests

response = requests.put(
    "https://api.spacefast.com/v1/spaces/string/variables/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "value": "string",
  "secret": True,
  "channelValues": {
    "property1": "string",
    "property2": "string"
  }
},
)

Response

{
  "$schema": "http://example.com",
  "data": {
    "name": "string",
    "scope": "space",
    "secret": true,
    "value": "string",
    "channelValues": {
      "property1": "string",
      "property2": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "operation": {
    "id": "string",
    "kind": "string",
    "status": "queued",
    "resources": [
      {
        "type": "string",
        "id": "string"
      }
    ],
    "progress": {
      "total": 9007199254740991,
      "completed": 9007199254740991,
      "failed": 9007199254740991
    },
    "diagnostics": [
      {
        "code": "string",
        "severity": "info",
        "message": "string",
        "path": "string",
        "provider": "infra",
        "details": {
          "property1": null,
          "property2": null
        },
        "fix": "string",
        "retryable": true
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "$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"
}