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

# Create Regions

POST https://api.makeswift.com/v1/regions/batch
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.

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.

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

Reference: https://docs.makeswift.com/developer/api-reference/rest/regions/create-regions

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

### Body (application/json)

This endpoint expects a CreateRegionsBatchV1BodyDto.

- `siteId` (string, required) — The site ID to create the regions in.
- `regions` (list of CreateRegionsBatchV1BodyDtoRegionsItems, required) — The regions to create, each like the body of Create Region.

## Response

### 200

- `list of CreateRegionsBatchV1ResponseDtoItems`

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

## Types

### CreateRegionsBatchV1BodyDtoRegionsItems

- `id` (string, required) — The region ID, assigned by the host. Unique within a site and locale.
- `name` (string, required) — The region name.
- `elements` (CreateRegionsBatchV1BodyDtoRegionsItemsElements, required) — The root of the region's element tree. Its component type becomes the region's `type`.
- `locale` (string, optional) — The locale to create the region in. Accepts either a locale code (e.g. `en-US`) or a `site_locale` UUID. Defaults to the site's default locale.

### CreateRegionsBatchV1ResponseDtoItems

### CreateRegionsBatchV1BodyDtoRegionsItemsElements

The root of the region's element tree. Its component type becomes the region's `type`.

- `type` (string, required) — The component type, e.g. './components/Box/index.js'.
- `key` (string, required) — A UUID, unique within this tree.
- `props` (map from string to any, required) — Control-defined values, keyed by prop name. Nested elements appear here too, as a \{ elements, columns } value that may sit under any prop name and at any depth - there is no reserved prop name for children.

### CreateRegionsBatchV1ResponseDtoItems0

- `success` (boolean, required)
- `data` (CreateRegionsBatchV1ResponseDtoItemsOneOf0Data, required)

### CreateRegionsBatchV1ResponseDtoItems1

- `success` (boolean, required)
- `error` (CreateRegionsBatchV1ResponseDtoItemsOneOf1Error, required)

### CreateRegionsBatchV1ResponseDtoItemsOneOf0Data

- `object` (enum, required)
  - Allowed values: `region`
- `id` (string, required) — The region ID. Assigned by the host, not generated by Makeswift.
- `name` (string, required) — The region name.
- `type` (string, required) — The component type at the root of the region's element tree.
- `locale` (string, required) — The locale of this region.
- `updatedAt` (datetime, required) — The region last update date and time.
- `version` (integer, required) — The version of the region's element tree. It increases with every change to the tree. Pass it to Update Region to update the region only if it has not changed since.
- `elements` (any, required) — Always `null` here. Get Region returns the region's element tree with `include=elements`.

### CreateRegionsBatchV1ResponseDtoItemsOneOf1Error

- `code` (enum, required) — `BASE_REGION_MISSING`: a region in a site locale whose region in the default locale does not exist. `REGION_EXISTS`: the region already exists in that locale. `INVALID_ELEMENT_TREE`: the element tree is invalid. `INVALID_LOCALE`: the site does not have the locale. `DUPLICATE_IN_BATCH`: an earlier region in the batch has the same `id` and locale. `INTERNAL_ERROR`: an unexpected error; the only one worth retrying.
  - Allowed values: `BASE_REGION_MISSING`, `REGION_EXISTS`, `INVALID_ELEMENT_TREE`, `INVALID_LOCALE`, `DUPLICATE_IN_BATCH`, `INTERNAL_ERROR`
- `message` (string, required)

## Examples

**Request**

```json
{
  "siteId": "123e4567-e89b-12d3-a456-426614174000",
  "regions": [
    {
      "id": "site-header",
      "name": "Site Header",
      "elements": {
        "type": "makeswift::components::slot::v1",
        "key": "0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21",
        "props": {
          "children": {
            "columns": [
              {
                "deviceId": "desktop",
                "value": {
                  "count": 12,
                  "spans": [
                    [
                      12
                    ]
                  ]
                }
              }
            ],
            "elements": [
              {
                "key": "7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d",
                "props": {
                  "alt": {
                    "@@makeswift/type": "text-input::v1",
                    "value": "Acme"
                  }
                },
                "type": "Logo"
              }
            ]
          }
        }
      }
    }
  ]
}
```

**Response**

```json
[
  {
    "data": {
      "elements": null,
      "id": "site-header",
      "locale": "en-US",
      "name": "Site Header",
      "object": "region",
      "type": "makeswift::components::slot::v1",
      "updatedAt": {},
      "version": 3
    },
    "success": true
  }
]
```

**SDK Code**

```python
import requests

url = "https://api.makeswift.com/v1/regions/batch"

payload = {
    "siteId": "123e4567-e89b-12d3-a456-426614174000",
    "regions": [
        {
            "id": "site-header",
            "name": "Site Header",
            "elements": {
                "type": "makeswift::components::slot::v1",
                "key": "0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21",
                "props": { "children": {
                        "columns": [
                            {
                                "deviceId": "desktop",
                                "value": {
                                    "count": 12,
                                    "spans": [[12]]
                                }
                            }
                        ],
                        "elements": [
                            {
                                "key": "7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d",
                                "props": { "alt": {
                                        "@@makeswift/type": "text-input::v1",
                                        "value": "Acme"
                                    } },
                                "type": "Logo"
                            }
                        ]
                    } }
            }
        }
    ]
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://api.makeswift.com/v1/regions/batch';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"siteId":"123e4567-e89b-12d3-a456-426614174000","regions":[{"id":"site-header","name":"Site Header","elements":{"type":"makeswift::components::slot::v1","key":"0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21","props":{"children":{"columns":[{"deviceId":"desktop","value":{"count":12,"spans":[[12]]}}],"elements":[{"key":"7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d","props":{"alt":{"@@makeswift/type":"text-input::v1","value":"Acme"}},"type":"Logo"}]}}}}]}'
};

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/v1/regions/batch"

	payload := strings.NewReader("{\n  \"siteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"regions\": [\n    {\n      \"id\": \"site-header\",\n      \"name\": \"Site Header\",\n      \"elements\": {\n        \"type\": \"makeswift::components::slot::v1\",\n        \"key\": \"0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21\",\n        \"props\": {\n          \"children\": {\n            \"columns\": [\n              {\n                \"deviceId\": \"desktop\",\n                \"value\": {\n                  \"count\": 12,\n                  \"spans\": [\n                    [\n                      12\n                    ]\n                  ]\n                }\n              }\n            ],\n            \"elements\": [\n              {\n                \"key\": \"7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d\",\n                \"props\": {\n                  \"alt\": {\n                    \"@@makeswift/type\": \"text-input::v1\",\n                    \"value\": \"Acme\"\n                  }\n                },\n                \"type\": \"Logo\"\n              }\n            ]\n          }\n        }\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", 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/v1/regions/batch")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"siteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"regions\": [\n    {\n      \"id\": \"site-header\",\n      \"name\": \"Site Header\",\n      \"elements\": {\n        \"type\": \"makeswift::components::slot::v1\",\n        \"key\": \"0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21\",\n        \"props\": {\n          \"children\": {\n            \"columns\": [\n              {\n                \"deviceId\": \"desktop\",\n                \"value\": {\n                  \"count\": 12,\n                  \"spans\": [\n                    [\n                      12\n                    ]\n                  ]\n                }\n              }\n            ],\n            \"elements\": [\n              {\n                \"key\": \"7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d\",\n                \"props\": {\n                  \"alt\": {\n                    \"@@makeswift/type\": \"text-input::v1\",\n                    \"value\": \"Acme\"\n                  }\n                },\n                \"type\": \"Logo\"\n              }\n            ]\n          }\n        }\n      }\n    }\n  ]\n}"

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.post("https://api.makeswift.com/v1/regions/batch")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"siteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"regions\": [\n    {\n      \"id\": \"site-header\",\n      \"name\": \"Site Header\",\n      \"elements\": {\n        \"type\": \"makeswift::components::slot::v1\",\n        \"key\": \"0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21\",\n        \"props\": {\n          \"children\": {\n            \"columns\": [\n              {\n                \"deviceId\": \"desktop\",\n                \"value\": {\n                  \"count\": 12,\n                  \"spans\": [\n                    [\n                      12\n                    ]\n                  ]\n                }\n              }\n            ],\n            \"elements\": [\n              {\n                \"key\": \"7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d\",\n                \"props\": {\n                  \"alt\": {\n                    \"@@makeswift/type\": \"text-input::v1\",\n                    \"value\": \"Acme\"\n                  }\n                },\n                \"type\": \"Logo\"\n              }\n            ]\n          }\n        }\n      }\n    }\n  ]\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.makeswift.com/v1/regions/batch', [
  'body' => '{
  "siteId": "123e4567-e89b-12d3-a456-426614174000",
  "regions": [
    {
      "id": "site-header",
      "name": "Site Header",
      "elements": {
        "type": "makeswift::components::slot::v1",
        "key": "0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21",
        "props": {
          "children": {
            "columns": [
              {
                "deviceId": "desktop",
                "value": {
                  "count": 12,
                  "spans": [
                    [
                      12
                    ]
                  ]
                }
              }
            ],
            "elements": [
              {
                "key": "7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d",
                "props": {
                  "alt": {
                    "@@makeswift/type": "text-input::v1",
                    "value": "Acme"
                  }
                },
                "type": "Logo"
              }
            ]
          }
        }
      }
    }
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.makeswift.com/v1/regions/batch");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"siteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"regions\": [\n    {\n      \"id\": \"site-header\",\n      \"name\": \"Site Header\",\n      \"elements\": {\n        \"type\": \"makeswift::components::slot::v1\",\n        \"key\": \"0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21\",\n        \"props\": {\n          \"children\": {\n            \"columns\": [\n              {\n                \"deviceId\": \"desktop\",\n                \"value\": {\n                  \"count\": 12,\n                  \"spans\": [\n                    [\n                      12\n                    ]\n                  ]\n                }\n              }\n            ],\n            \"elements\": [\n              {\n                \"key\": \"7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d\",\n                \"props\": {\n                  \"alt\": {\n                    \"@@makeswift/type\": \"text-input::v1\",\n                    \"value\": \"Acme\"\n                  }\n                },\n                \"type\": \"Logo\"\n              }\n            ]\n          }\n        }\n      }\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "siteId": "123e4567-e89b-12d3-a456-426614174000",
  "regions": [
    [
      "id": "site-header",
      "name": "Site Header",
      "elements": [
        "type": "makeswift::components::slot::v1",
        "key": "0b8f2f4e-3c1d-4e7a-9f2b-8a6c5d4e3f21",
        "props": ["children": [
            "columns": [
              [
                "deviceId": "desktop",
                "value": [
                  "count": 12,
                  "spans": [[12]]
                ]
              ]
            ],
            "elements": [
              [
                "key": "7d3e9a1b-5c2f-4b8e-a6d4-2f1e0c9b8a7d",
                "props": ["alt": [
                    "@@makeswift/type": "text-input::v1",
                    "value": "Acme"
                  ]],
                "type": "Logo"
              ]
            ]
          ]]
      ]
    ]
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.makeswift.com/v1/regions/batch")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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()
```