> This page is for Changelog.

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

# Changelog

## October 19, 2026

## List pages with their element trees from the REST API

The List Pages endpoint now accepts `include=elements`, returning each page's element tree alongside the page records.

```bash
GET /v6/pages?siteId={siteId}&include=elements
```

* **Opt-in**: omit `include` and every page's `elements` is `null`. `include` accepts only `elements` (any other value returns a `400`).

> **Note**
>
> `include=elements` is in beta and may change. Requests that pass it return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see the [`include` parameter](/developer/api-reference/rest/pages/list-pages#request.query.include) on List Pages.

## October 15, 2026

## Create regions in batches from the REST API

A new `v1` endpoint creates many regions in one request.

#### Create Regions

```bash
POST /v1/regions/batch
```

Creates up to 1000 regions, each like Create Region. Each region is created on its own: the response has one result per region, in request order, and a region that fails does not stop the others.

```json
[
  { "success": true, "data": { "object": "region", "id": "header", "version": 1, ... } },
  { "success": false, "error": { "code": "REGION_EXISTS", "message": "..." } }
]
```

* **Error codes**: a failed region reports `REGION_EXISTS`, `BASE_REGION_MISSING`, `INVALID_LOCALE`, `INVALID_ELEMENT_TREE`, `DUPLICATE_IN_BATCH`, or `INTERNAL_ERROR`. Only `INTERNAL_ERROR` is worth retrying.
* **Default locale first**: regions in the default locale are created before regions in site locales, so a region in a site locale may come before its default locale's region in the same batch.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [Create Regions](/developer/api-reference/rest/regions/create-regions).

## October 13, 2026

## Update and delete regions from the REST API

Two new `v1` endpoints complete the region API: you can now replace a region's element tree and delete a region.

#### Update Region

```bash
PATCH /v1/regions/{id}?siteId={siteId}
```

Replaces a region's element tree in one locale. The component `type` at the root of `elements` becomes the region's `type`. Updating the default locale also updates the localized regions that inherit from it.

#### Delete Region

```bash
DELETE /v1/regions/{id}?siteId={siteId}
```

Deletes a region in one locale. Only the draft changes: the live site changes when you publish.

* **Region versions**: every region response now includes `version`, which increases with every change to the region's element tree.
* **Safe updates**: pass the `version` from an earlier read to Update Region. If the region changed since, the request returns `409` and changes nothing. Leave `version` out to update the region regardless.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [Update Region](/developer/api-reference/rest/regions/update-region) and [Delete Region](/developer/api-reference/rest/regions/delete-region).

## October 13, 2026

## Update and delete regions from the REST API

Two new `v1` endpoints complete the region API: you can now replace a region's element tree and delete a region.

#### Update Region

```bash
PATCH /v1/regions/{id}?siteId={siteId}
```

Replaces a region's element tree in one locale. The component `type` at the root of `elements` becomes the region's `type`. Updating the default locale also updates the localized regions that inherit from it.

#### Delete Region

```bash
DELETE /v1/regions/{id}?siteId={siteId}
```

Deletes a region in one locale. Only the draft changes: the live site changes when you publish.

* **Region versions**: every region response now includes `version`, which increases with every change to the region's element tree.
* **Safe updates**: pass the `version` from an earlier read to Update Region. If the region changed since, the request returns `409` and changes nothing. Leave `version` out to update the region regardless.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [Update Region](/developer/api-reference/rest/regions/update-region) and [Delete Region](/developer/api-reference/rest/regions/delete-region).

## October 7, 2026

## Manage regions from the REST API

Three new `v1` endpoints let you create, list, and read a site's regions, including their element trees, from the REST API.

#### List Regions

```bash
GET /v1/regions?siteId={siteId}
```

Returns a site's regions for one locale, with cursor-based pagination through `limit` (1–100, default 20) and `startingAfter`.

#### Create Region

```bash
POST /v1/regions
```

Creates a region in one locale. `siteId`, `id`, `name`, and `elements` are required. The component `type` at the root of `elements` becomes the region's `type`. Returns `409` if the region already exists.

#### Get Region

```bash
GET /v1/regions/{id}?siteId={siteId}
```

Returns a single region in one locale. URL-encode the `id` if it contains reserved characters such as `/`.

* **You choose the ID**: Makeswift doesn't generate region IDs. You assign the ID (for example, `site-header`), and it must be unique within a site and locale.
* **One locale per request**: all three endpoints accept a `locale` parameter, as either a locale code like `en-US` or a site locale UUID. If you leave it out, the request uses the site's default locale. A region has to exist in the default locale before you can create it in another locale.
* **Element trees are optional**: pass `include=elements` to List Regions or Get Region to get each region's element tree. Without it, `elements` is `null`.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [List Regions](/developer/api-reference/rest/regions/list-regions), [Create Region](/developer/api-reference/rest/regions/create-region), and [Get Region](/developer/api-reference/rest/regions/get-region).

## October 7, 2026

## Manage regions from the REST API

Three new `v1` endpoints let you create, list, and read a site's regions, including their element trees, from the REST API.

#### List Regions

```bash
GET /v1/regions?siteId={siteId}
```

Returns a site's regions for one locale, with cursor-based pagination through `limit` (1–100, default 20) and `startingAfter`.

#### Create Region

```bash
POST /v1/regions
```

Creates a region in one locale. `siteId`, `id`, `name`, and `elements` are required. The component `type` at the root of `elements` becomes the region's `type`. Returns `409` if the region already exists.

#### Get Region

```bash
GET /v1/regions/{id}?siteId={siteId}
```

Returns a single region in one locale. URL-encode the `id` if it contains reserved characters such as `/`.

* **You choose the ID**: Makeswift doesn't generate region IDs. You assign the ID (for example, `site-header`), and it must be unique within a site and locale.
* **One locale per request**: all three endpoints accept a `locale` parameter, as either a locale code like `en-US` or a site locale UUID. If you leave it out, the request uses the site's default locale. A region has to exist in the default locale before you can create it in another locale.
* **Element trees are optional**: pass `include=elements` to List Regions or Get Region to get each region's element tree. Without it, `elements` is `null`.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [List Regions](/developer/api-reference/rest/regions/list-regions), [Create Region](/developer/api-reference/rest/regions/create-region), and [Get Region](/developer/api-reference/rest/regions/get-region).

## October 7, 2026

## Manage regions from the REST API

Three new `v1` endpoints let you create, list, and read a site's regions, including their element trees, from the REST API.

#### List Regions

```bash
GET /v1/regions?siteId={siteId}
```

Returns a site's regions for one locale, with cursor-based pagination through `limit` (1–100, default 20) and `startingAfter`.

#### Create Region

```bash
POST /v1/regions
```

Creates a region in one locale. `siteId`, `id`, `name`, and `elements` are required. The component `type` at the root of `elements` becomes the region's `type`. Returns `409` if the region already exists.

#### Get Region

```bash
GET /v1/regions/{id}?siteId={siteId}
```

Returns a single region in one locale. URL-encode the `id` if it contains reserved characters such as `/`.

* **You choose the ID**: Makeswift doesn't generate region IDs. You assign the ID (for example, `site-header`), and it must be unique within a site and locale.
* **One locale per request**: all three endpoints accept a `locale` parameter, as either a locale code like `en-US` or a site locale UUID. If you leave it out, the request uses the site's default locale. A region has to exist in the default locale before you can create it in another locale.
* **Element trees are optional**: pass `include=elements` to List Regions or Get Region to get each region's element tree. Without it, `elements` is `null`.

> **Note**
>
> The region endpoints are in beta and may change. Requests return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [List Regions](/developer/api-reference/rest/regions/list-regions), [Create Region](/developer/api-reference/rest/regions/create-region), and [Get Region](/developer/api-reference/rest/regions/get-region).

## October 1, 2026

## Write a page's element tree from the REST API

The Create Page and Update Page endpoints now accept an optional `elements` field, so you can set a page's element tree when you create or update the page.

```bash
POST /v6/pages
PATCH /v6/pages/{pageIdOrPathname}
```

* **Create**: if you leave out `elements`, the page starts with an empty root.
* **Update**: if you send `elements`, it replaces the page's entire tree.
* **Tree shape**: the root node has `type` set to `./components/Root/index.js`, a `key` (a UUID that's unique within the tree), and `props`. This is the same shape that `include=elements` returns on Get Page.
* **Responses**: Create Page and Update Page return `elements: null`. To read the tree after a write, call Get Page with `include=elements`.

### Error response changes

* A pathname that's invalid or already in use now returns `400` instead of `409`. A `400` is also returned for an invalid element tree.
* Create Page returns `404` if the site doesn't exist. Update Page returns `404` if the page or its site doesn't exist.

> **Note**
>
> The `elements` field is in beta and may change. Requests that send it return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [Create Page](/developer/api-reference/rest/pages/create-page) and [Update Page](/developer/api-reference/rest/pages/update-page).

## September 29, 2026

## Manage site swatches from the REST API

Five new `v4` endpoints let you create, read, update, and delete a site's colors from the REST API.

#### List Swatches

```bash
GET /v4/swatches?siteId={siteId}
```

Returns a site's swatches, with cursor-based pagination through `limit` (1–100, default 20) and `startingAfter`.

#### Create Swatch

```bash
POST /v4/swatches
```

Adds a swatch to a site. `siteId`, `hue`, `saturation`, and `lightness` are required; `name` is optional.

#### Get Swatch

```bash
GET /v4/swatches/{id}
```

Returns a single swatch.

#### Update Swatch

```bash
PATCH /v4/swatches/{id}
```

Changes a swatch's `name`, `hue`, `saturation`, or `lightness`. Omitted fields keep their current values. Swatches are grouped by name prefix, so renaming `White` to `Neutrals / White` moves the swatch into the `Neutrals` group.

#### Delete Swatch

```bash
DELETE /v4/swatches/{id}
```

Removes a swatch.

Each swatch stores its color as HSL values: `hue` (0–360), `saturation` (0–100), and `lightness` (0–100).

The GET apis both provide `id` and `referenceId` for each swatch returned. All 5 endpoints above use `id`. `referenceId` is the value that appears as swatchId in a page's element tree (GET /v6/pages/:id?include=elements). Use it as a reference to find swatches in page content.

> **Note**
>
> The swatch endpoints are currently in beta and may change. Requests return 403 until the feature is enabled for your site or workspace. To opt-in, please contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see [List Swatches](/developer/api-reference/rest/swatches/list-swatches), [Create Swatch](/developer/api-reference/rest/swatches/create-swatch), [Get Swatch](/developer/api-reference/rest/swatches/get-swatch), [Update Swatch](/developer/api-reference/rest/swatches/update-swatch), and [Delete Swatch](/developer/api-reference/rest/swatches/delete-swatch).

## September 28, 2026

## Docs MCP Server: clearer scope and Claude Code setup

Thanks to user feedback, the page for connecting AI tools to the Makeswift docs is now [Docs MCP Server](/product/docs/ai-agent-setup), says up front what the server does, and clarifies the Claude Code setup instructions.

* **Docs search only.** The server lets your agent search and reference the documentation. It has no access to your sites, pages, or workspace settings. To work with site data, use the [Makeswift API](/developer/api-reference/overview).
* **Claude Code setup in three steps.** Copy, run, confirm, with the single-project and every-project (`--scope user`) commands shown side by side so you pick before you run.
* **Buttons described accurately.** **Connect to Cursor** installs the server directly. **Connect to Claude Code** copies the install command for you to paste.

## September 18, 2026

## Read a page's element tree from the REST API

The Get Page endpoint now accepts `include=elements`, returning the page's full element tree alongside the page record.

```bash
GET /v6/pages/{pageIdOrPathname}?include=elements
```

* **Opt-in** — omit `include` and `elements` is `null`. `include` accepts only `elements` (any other value returns a `400`).
* **Respects existing resolution** — the returned tree honors the same `locale` and `versionRef` parameters as the endpoint. `?locale=` returns the localized tree; `?versionRef=ref:live` returns the published tree (default is `ref:draft`).
* **Tree shape** — each node has a `type`, a `key` (a UUID unique within the tree), and `props`. Nested elements live inside `props`, at any depth.

> **Note**
>
> `include=elements` is in beta and may change. Requests that pass it return `403` until the feature is enabled for your site or workspace. To opt in, contact support: [support@makeswift.com](mailto:support@makeswift.com).

For details, see the [`include` parameter](/developer/api-reference/rest/pages/get-page#request.query.include) on Get Page.

## August 14, 2026

## Navigation Sidebar updates

The Navigation Sidebar has been reorganized around a split pane that shows your pages and the Elements Panel at the same time, and you can now sort elements directly in the Elements Panel.

![The Navigation Sidebar showing Content and Design tabs, a list of pages in the top pane, and the Elements Panel in the bottom pane](/_fern-img/bf46a651cfaefc22502123617f8268fa6d88d778e85c51e689bfde803ad3954b.webp)

* **Split pane for pages and elements** — pages and the Elements Panel share the sidebar, so you can move between pages and inspect the structure of the current page without switching panels.
* **Settings in the site switcher** — workspace and site settings have moved into the site switcher menu at the top of the sidebar.
* **Files manager button** — files open from the button beside the **Content** and **Design** tabs.
* **Updated Help button** — the **?** button in the bottom left now opens **Contact support**, **View docs**, **Shortcuts**, and the updated [Diagnostics dialog](/changelog/2026/8/3) for gathering diagnostic information.
* **Sort elements in the Elements Panel** — drag an element in the Elements Panel to reorder it within its parent, without dragging it on the Canvas.

For details, see [The basics](/product/docs/the-visual-builder/builder-basics).

## August 12, 2026

## Sort elements using keyboard arrows

Select an element in the Canvas or Elements Panel in the left sidebar and press an arrow key to move it within its parent, without dragging it.

* **Left and right** — reorder an element with its direct siblings in the same Box or Slot row.
* **Up and down** — move an element between rows, when it sits in a row by itself and the adjacent row above or below also holds a single element.
* **Scoped to the parent** — arrow keys move an element within its Box or Slot only.

## August 11, 2026

## Resource References in the Visual Builder

Some resource changes affect more than one page. Resource References show all of the places a resource is used, so you can add, edit, and delete resources with confidence.

![A color's edit panel showing a Used in n places item, expanded to a list of pages and regions, with a page expanded to show its locales](/_fern-img/e3e8fd1fdf73a2fd893dfd0d35790c13f533542357b0a0ce6d8bff5cb33c5546.webp)

* **Supported resources:** colors, text styles, files, and global components.
* **Usage count in context:** a **Used in *n* place(s)** item appears in the resource's **Action Menu** (⋯), or in a color or text style's edit panel.
* **Pages and regions:** the submenu lists the pages using the resource, plus the regions using it. Click a page to navigate to it; regions are listed for reference only, since they can be shared across multiple pages.
* **Locale aware:** expand a page to see which locales use the resource, and navigate straight to that page in a specific locale.

> **Note**
>
> References are tracked through pages and regions, not through global components or text styles. A color that is used inside a global component that is used on 3 pages will report as being used on 3 pages. If that global component is not used on any pages or regions, the color will show no resource references.

For details, see [Resource References](/product/docs/guides/publishing#resource-references).

## August 3, 2026

## Diagnostics dialog in the Visual Builder

The **Copy diagnostics** item in the Visual Builder Help menu has been replaced with **Diagnostics**, which opens a dialog where you can review diagnostic information before sharing it.

![The Diagnostics dialog showing builder identifiers, host information, and host connection details](/_fern-img/c5097728f92543c946a82f8434c05bb49ed506c446395b3b9480963ed5cb9d00.webp)

* **Review before you share:** diagnostics are grouped into sections for builder identifiers, host information, host connection, selection, and browser information.
* **Copy or download:** copy a readable report, copy the full diagnostics data, or download it as a ZIP file to attach to a support request.
* **Section-level copying:** copy an individual section instead of the whole report.

For details, see [Diagnostics](/product/docs/guides/troubleshooting/diagnostics).

## July 23, 2026

## Availability badges in the sidebar

The documentation site now shows availability badges in the sidebar navigation, making it easier to spot the status of a page before you open it. This is a documentation-site improvement, not a change to Makeswift itself.

* **Beta and deprecated indicators:** pages marked beta or deprecated now surface that status directly in the sidebar.
* **Faster scanning:** identify pre-release and legacy content at a glance while browsing the navigation.

## July 16, 2026

## Apps are now generally available

Apps are out of Early Access and available to everyone. You no longer need to enable an early access setting before creating an app to authenticate with the Makeswift REST API.

* **No setup required** — head straight to **Settings** → **Workspace** → **Apps** to create an app and get your API key.

For details, see [Authentication](/developer/api-reference/authentication).

## June 23, 2026

## New IconRadioGroup control

The `IconRadioGroup` control adds an icon-based radio group panel to the Makeswift builder, letting developers offer visual icon options for component properties like alignment, layout direction, or style variants.

![An IconRadioGroup panel in the Makeswift builder with rows of selectable alignment and icon options](/_fern-img/6f79f130a83df75381b0c7ac78298738842131c8a7ecd6493907b89ffd28f89f.webp)

* **Kebab-case icon values** — Pass icons as bare strings (e.g., `"text-align-left"`, `"arrow-right"`) or use the `IconRadioGroup.Icon` accessor
* **169 built-in icons** — Full set of icons covering alignment, arrows, layout, logos, and more
* **Typed generic prop** — The control passes the selected option's `value` as a typed string to your component

### Example

```tsx
import { IconRadioGroup } from "@makeswift/runtime/controls";

runtime.registerComponent(TextBlock, {
  type: "text-block",
  label: "Text Block",
  props: {
    alignment: IconRadioGroup({
      label: "Alignment",
      options: [
        { value: "left", label: "Left", icon: "text-align-left" },
        { value: "center", label: "Center", icon: "text-align-center" },
        { value: "right", label: "Right", icon: "text-align-right" },
      ],
      defaultValue: "left",
    }),
  },
});
```

For full documentation, see the [IconRadioGroup control reference](/developer/docs/reference/controls/icon-radio-group).

## June 17, 2026

## Connect our docs to your AI agent

We've added a dedicated [AI Agent Setup](/product/docs/ai-agent-setup) page that walks you through connecting the Makeswift docs to your AI tool — so it can answer questions grounded in our documentation instead of guessing.

* **One-click install** for Cursor and Claude Code via the **Copy page** dropdown in the upper-right of any docs page
* **Manual setup snippets** for Cursor, Claude Code, Codex, and Claude Desktop
* **Bottom-pinned sidebar link** on every tab so the page is reachable from anywhere on the site

Powered by the docs site's MCP server at `https://docs.makeswift.com/_mcp/server`.

## June 10, 2026

## Quickly jump between Makeswift, BigCommerce, and Feedonomics docs

Thanks to your feedback, the header logo is now a site switcher. Click the logo at the top-left of any page to open a dropdown and jump straight to the [BigCommerce](https://docs.bigcommerce.com/developer) or [Feedonomics](https://docs.feedonomics.com) docs without leaving your tab.

![Makeswift logo opened to reveal a dropdown with links to the BigCommerce and Feedonomics docs sites](/_fern-img/9e17b21eea4ebcd38ad4754991c69dbe9097f69988d33d646cd3530c78157758.webp)

Keep the feedback coming.

_Showing the 20 most recent of 26 entries. Append `/llms.txt` to the changelog URL for the complete index._