Skip to navigation
RESTSwatches

Update Swatch

This feature is in beta and may change. Requests return 403 until the feature flag is enabled for your site or workspace.

Updates a site-owned swatch color and name by swatchId. All fields are optional, thus omitted fields keep their current values.

Authentication

x-api-keystring

API key authentication. Accepts either:

  • App API key (e.g. sk_eczMHVBY9fV6GYFhvs53qcnxq7yptlXL3ABKOZtn6dQ)
  • Site API key (UUID format, e.g. 550e8400-e29b-41d4-a716-446655440000)

Path parameters

idstringRequiredformat: "uuid"
The ID of the swatch.

Request

This endpoint expects an object.
namestringOptional>=1 character

The name of the swatch. This field is optional, and omitting it leaves the current name unchanged. Null or empty strings are not permitted. Swatch groups are sorted based on name prefix, thus changing from ‘White’ to ‘Neutrals / White’ will move the swatch into the site’s corresponding swatch group

huedoubleOptional0-360

Hue value between [0, 360]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.

saturationdoubleOptional0-100

Saturation value between [0, 100]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.

lightnessdoubleOptional0-100

Lightness value between [0, 100]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.

Response

idstringformat: "uuid"
referenceIdstring

The id to use wherever a color prop references this swatch (e.g. the “swatchId” inside backgrounds/border/boxShadow/text-color payloads) - NOT the plain “id” field above which is used in other api calls like update_swatch.

namestring or null
huedouble0-360
saturationdouble0-100
lightnessdouble0-100
siteIdstringformat: "uuid"
pageIdstring or nullformat: "uuid"

Always null here. Page-owned swatches are not available through this API.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error