Skip to navigation
RESTSwatches

Create Swatch

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

Creates a site owned swatch.

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)

Request

This endpoint expects an object.
siteIdstringRequiredformat: "uuid"
The site ID to create the swatch on.
huedoubleRequired0-360

Hue value between [0, 360].

saturationdoubleRequired0-100

Saturation value between [0, 100].

lightnessdoubleRequired0-100

Lightness value between [0, 100].

namestring or nullOptional
The name of the swatch.

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