Skip to content
Docs
Esc
↑↓navigate↵open⌘Jpreview

Save a team's design-system changes

Atomically saves partial color, typography, layout, tone, rule, and asset-guidance changes. Omitted fields stay unchanged; null clears optional values. Entries in upserts without IDs create records. changes lists changed colors, rules, and assets in that collection order, with upserts then removals in request order, followed by typography, layout, and tone; unchanged entries are omitted. Remove archives a record. Pass the current expectedRevision (0 for the first save); a stale revision returns 409. Reuse operationId and identical input after an uncertain response. Upload asset bytes separately, then reference the returned attachmentId. A save does not modify any Space’s site files. Requires the team context beta.

POST/v1/teams/{teamId}/design-system/changes
Authorization
AuthorizationBearer token · headerrequired

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

or
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
teamIdstringrequired
min length 1
Request body
requiredapplication/json
operationIdstringrequired
min length 1 · max length 128
expectedRevisionintegerrequired
min 0 · max 9007199254740991
changesobjectrequired
Show properties
colorsobject
Show properties
upsertobject[]
max items 100
Show properties
Array of object
namestring
min length 1 · max length 80
hexstring
matches ^#[A-Fa-f0-9]{6}(?:[A-Fa-f0-9]{2})?$
usagestring | null
Show properties
Any of:
string
string
null
null
idstring<uuid>
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
removestring<uuid>[]
max items 100
typographyobject
Show properties
headingsobject | null
Show properties
Any of:
object
fontSizePxnumberrequired
min 0 · max 100000
lineHeightPxnumberrequired
min 0 · max 100000
fontFamilystringrequired
min length 1 · max length 255
h2object | null
Show properties
Any of:
object
fontSizePxnumberrequired
min 0 · max 100000
lineHeightPxnumberrequired
min 0 · max 100000
null
null
h3object | null
Show properties
Any of:
object
fontSizePxnumberrequired
min 0 · max 100000
lineHeightPxnumberrequired
min 0 · max 100000
null
null
null
null
bodyobject | null
Show properties
Any of:
object
fontSizePxnumberrequired
min 0 · max 100000
lineHeightPxnumberrequired
min 0 · max 100000
fontFamilystringrequired
min length 1 · max length 255
null
null
headingCasestring | null
Show properties
Any of:
string
string
null
null
layoutobject
Show properties
pageWidthPxnumber | null
Show properties
Any of:
number
number
null
null
cornerRadiusPxnumber | null
Show properties
Any of:
number
number
null
null
sectionSpacingPxnumber | null
Show properties
Any of:
number
number
null
null
voiceobject
Show properties
tonestring | null
Show properties
Any of:
string
string
null
null
rulesobject
Show properties
upsertobject[]
max items 100
Show properties
Array of object
textstring
min length 1 · max length 32768
examplestring | null
Show properties
Any of:
string
string
null
null
idstring<uuid>
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
removestring<uuid>[]
max items 100
assetsobject
Show properties
upsertobject[]
max items 100
Show properties
Array of object
attachmentIdinteger
max 9007199254740991
categorystring | null
Show properties
Any of:
string
string
null
null
usagestring | null
Show properties
Any of:
string
string
null
null
altTextstring | null
Show properties
Any of:
string
string
null
null
idstring<uuid>
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
removestring<uuid>[]
max items 100
Responses
200

Response 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
revisionintegerrequired
min 0 · max 9007199254740991
actionIdstring<uuid> | nullrequired
Show properties
Any of:
string<uuid>
string<uuid>
null
null
unchangedbooleanrequired
changesobject[]required
Show properties
Array of object
idstringrequired
typestringrequired
Allowed:colortypographylayouttoneruleasset
actionstringrequired
Allowed:createdupdatedremovedrestored
default

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

fixstring

One sentence on what to do about this error code, the same text as the type page. Read it before retrying.

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.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.spacefast.com/v1/teams/string/design-system/changes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "operationId": "string",
  "expectedRevision": 0,
  "changes": {
    "colors": {
      "upsert": [
        {
          "name": "string",
          "hex": "string",
          "usage": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      ],
      "remove": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ]
    },
    "typography": {
      "headings": {
        "fontSizePx": 0,
        "lineHeightPx": 0,
        "fontFamily": "string",
        "h2": {
          "fontSizePx": 0,
          "lineHeightPx": 0
        },
        "h3": {
          "fontSizePx": 0,
          "lineHeightPx": 0
        }
      },
      "body": {
        "fontSizePx": 0,
        "lineHeightPx": 0,
        "fontFamily": "string"
      },
      "headingCase": "sentence"
    },
    "layout": {
      "pageWidthPx": 0,
      "cornerRadiusPx": 0,
      "sectionSpacingPx": 0
    },
    "voice": {
      "tone": "string",
      "rules": {
        "upsert": [
          {
            "text": "string",
            "example": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "remove": [
          "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
      }
    },
    "assets": {
      "upsert": [
        {
          "attachmentId": 1,
          "category": "logo",
          "usage": "string",
          "altText": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      ],
      "remove": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ]
    }
  }
}'
Response
{
  "$schema": "http://example.com",
  "data": {
    "revision": 0,
    "actionId": "4a2794ff-94cb-4bac-8d36-d5fb36c563a0",
    "unchanged": true,
    "changes": [
      {
        "id": "string",
        "type": "color",
        "action": "created"
      }
    ]
  }
}

Was this page helpful?