Changelog

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.

GET /v1/regions?siteId={siteId}

POST /v1/regions

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

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

For details, see List Regions, Create Region, and Get Region.

Runtime v0.29.0

@makeswift/runtime v0.29.0 fetches snapshots faster and rebuilds how Makeswift generates CSS and applies style updates. It also has breaking changes that may require updates to your host.

• React 19 required. Your host must run React 19. Next.js hosts must be on Next.js 15 or later.
• cacheKey renamed to classNamePrefix. The cacheKey prop on <RootStyleRegistry> is now classNamePrefix (default ms). Use it to set a custom prefix for Makeswift-generated CSS class names.
• <RootStyleRegistry> required for Pages Router. Pages Router hosts must now wrap their content in <RootStyleRegistry> inside ReactRuntimeProvider:

<ReactRuntimeProvider runtime={runtime} siteVersion={siteVersion}>
  <RootStyleRegistry>
    <Component {...pageProps} />
  </RootStyleRegistry>
</ReactRuntimeProvider>

• New forceImportant prop. Set forceImportant on <RootStyleRegistry> to add !important to Makeswift-generated CSS declarations, so they win when your site’s own CSS conflicts with them.

For migration steps, see the v0.29.0 upgrade guide. For component details, see the <RootStyleRegistry> reference.

Manage site typographies from the REST API

Four new v4 endpoints let you create, read, and update a site’s typographies (the text styles in the Visual Builder) from the REST API.

GET /v4/typographies?siteId={siteId}

POST /v4/typographies

GET /v4/typographies/{id}

PATCH /v4/typographies/{id}

• Per-device styles: style is an array of { deviceId, value } entries. Each value can set fontFamily, fontSize ({ value, unit }), fontWeight, lineHeight, letterSpacing, textAlign, italic, underline, strikethrough, uppercase, and color.
• Colors come from swatches: color.swatchId takes the id of an existing swatch, so create the swatch first with the Swatch API. color.alpha (0–1) sets opacity.
• Two IDs: the typography endpoints use id. referenceId is the value a Text element’s typography prop uses in a page’s element tree, so use it to find a typography in page content.

For details, see List Typographies, Create Typography, Get Typography, and Update Typography.

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.

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.

For details, see Create Page and Update Page.

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.

GET /v4/swatches?siteId={siteId}

POST /v4/swatches

GET /v4/swatches/{id}

PATCH /v4/swatches/{id}

DELETE /v4/swatches/{id}

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.

For details, see List Swatches, Create Swatch, Get Swatch, Update Swatch, and Delete Swatch.

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

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.

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.

For details, see the include parameter on Get Page.

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.

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

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.

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.

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

For details, see Resource References.