Changelog

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.

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

For details, see the include parameter on List Pages.

Create regions in batches from the REST API

A new v1 endpoint creates many regions in one request.

POST /v1/regions/batch

[
  { "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.

For details, see Create Regions.

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.

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

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

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

For details, see Update Region and Delete Region.

Delete typographies from the REST API

A new v4 endpoint lets you delete a site’s typography.

DELETE /v4/typographies/{id}

The delete is unconditional: Text elements that still reference the typography aren’t checked, so update them first if they should keep a style.

For details, see Delete Typography.

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.