> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.makeswift.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.makeswift.com/_mcp/server.

# Update Swatch

PATCH https://api.makeswift.com/v4/swatches/{id}
Content-Type: application/json

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.

Reference: https://docs.makeswift.com/developer/api-reference/rest/swatches/update-swatch

## Authentication

- `x-api-key` header (required) — 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

### Path parameters

- `id` (string, required) — The ID of the swatch.

### Body (application/json)

This endpoint expects an UpdateSwatchV4BodyDto.

- `name` (string, optional) — 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
- `hue` (double, optional) — Hue value between [0, 360]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.
- `saturation` (double, optional) — Saturation value between [0, 100]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.
- `lightness` (double, optional) — Lightness value between [0, 100]. This field is optional, and omitting it leaves the current value unchanged. Null is not permitted.

## Response

### 200

- `id` (string, required)
- `referenceId` (string, required) — 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.
- `name` (string, required, nullable)
- `hue` (double, required)
- `saturation` (double, required)
- `lightness` (double, required)
- `siteId` (string, required)
- `pageId` (string, required, nullable) — Always `null` here. Page-owned swatches are not available through this API.

## Errors

### 400 Bad Request Error

- `object` (enum, required)
  - Allowed values: `error`
- `code` (enum, required)
  - Allowed values: `bad_request`
- `message` (string, required)

### 403 Forbidden Error

- `object` (enum, required)
  - Allowed values: `error`
- `code` (enum, required)
  - Allowed values: `forbidden`
- `message` (string, required)

### 404 Not Found Error

- `object` (enum, required)
  - Allowed values: `error`
- `code` (enum, required)
  - Allowed values: `not_found`
- `message` (string, required)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "id": "8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d",
  "referenceId": "U3dhdGNoOjhhMWYzYzJkLTViNmUtNGY3YS05YzBkLTFlMmYzYTRiNWM2ZA==",
  "name": "Brand / Pink",
  "hue": 322,
  "saturation": 81,
  "lightness": 58,
  "siteId": "123e4567-e89b-12d3-a456-426614174000",
  "pageId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d"

payload = {}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d';
const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.patch("https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d");
var request = new RestRequest(Method.PATCH);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.makeswift.com/v4/swatches/8a1f3c2d-5b6e-4f7a-9c0d-1e2f3a4b5c6d")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```