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

# List Regions

GET https://api.makeswift.com/v1/regions

This feature is in beta and may change. Requests return `403` until the feature flag is enabled for your site or workspace.

Lists a site's regions for one locale. Element trees are included only with `include=elements`.

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

## Authentication

- `x-api-key` header (required) — API key authentication with an App API key (e.g. sk_eczMHVBY9fV6GYFhvs53qcnxq7yptlXL3ABKOZtn6dQ).
- `x-api-key` header (required) — Site API key (UUID format, e.g. 550e8400-e29b-41d4-a716-446655440000).

## Request

### Query parameters

- `siteId` (string, required) — The site ID to list regions from.
- `limit` (integer, optional, default: 20) — The maximum number of regions to return.
- `startingAfter` (string, optional) — The pagination cursor. This is used to indicate what ID to list from.
- `locale` (string, optional) — The locale to list regions for. Accepts either a locale code (e.g. `en-US`) or a `site_locale` UUID. Defaults to the site's default locale.
- `include` (enum, optional) — Include additional data in the response. Omit for the region records alone. Supported values: - `elements` - include each region's element tree.
  - Allowed values: `elements`

## Response

### 200

- `object` (enum, required)
  - Allowed values: `list`
- `data` (list of ListRegionsV1ResponseDtoDataItems, required) — The regions on the site in the requested locale.
- `hasMore` (boolean, required) — The flag that indicates whether there are more regions available.

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

### ListRegionsV1ResponseDtoDataItems

- `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` (ListRegionsV1ResponseDtoDataItemsElements, required, nullable) — The root of the region's element tree. `null` unless `include=elements`.

### ListRegionsV1ResponseDtoDataItemsElements

The root of the region's element tree. `null` unless `include=elements`.

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

## Examples

**Response**

```json
{
  "object": "list",
  "data": [
    {
      "object": "region",
      "id": "site-header",
      "name": "Site Header",
      "type": "makeswift::components::slot::v1",
      "locale": "en-US",
      "updatedAt": {},
      "version": 3,
      "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"
              }
            ]
          }
        }
      }
    }
  ],
  "hasMore": false
}
```

**SDK Code**

```python
import requests

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

querystring = {"limit":"20","locale":"en-US","siteId":"123e4567-e89b-12d3-a456-426614174000","startingAfter":"site-header"}

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

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"
	"net/http"
	"io"
)

func main() {

	url := "https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	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?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

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.get("https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header")
  .header("x-api-key", "<apiKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.makeswift.com/v1/regions?limit=20&locale=en-US&siteId=123e4567-e89b-12d3-a456-426614174000&startingAfter=site-header")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

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()
```