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

# Overview

> Programmatically manage your Makeswift sites, pages, and locales.

Programmatically manage your Makeswift sites, pages, and locales.

The Makeswift REST API allows you to programmatically manage your Makeswift resources. Use it to automate workflows, integrate with external systems, or build custom tooling.

## Base URL

All API requests should be made to:

```
https://api.makeswift.com
```

## Authentication

Authenticate requests by including an App API key in the `x-api-key` header:

```bash
curl https://api.makeswift.com/v2/sites \
  -H "x-api-key: your-api-key"
```

> **Note**
>
> See the [Authentication guide](/developer/api-reference/authentication) to
> learn how to create an app and get your API key.

## Resources

| Resource                                                       | Description                                       |
| -------------------------------------------------------------- | ------------------------------------------------- |
| [Sites](/developer/api-reference/rest/sites/create-site)       | Create, read, update, delete, and duplicate sites |
| [Locales](/developer/api-reference/rest/locales/create-locale) | Configure localization settings                   |
| [Pages](/developer/api-reference/rest/pages/create-page)       | Manage pages within a site                        |

## Response format

All responses return JSON. Successful responses include an `object` field indicating the resource type:

```json
{
  "object": "site",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Site"
}
```

List endpoints return paginated results:

```json
{
  "object": "list",
  "data": [...],
  "hasMore": true
}
```

## Pagination

List endpoints support cursor-based pagination using the following query parameters:

| Parameter       | Type   | Default | Description                                              |
| --------------- | ------ | ------- | -------------------------------------------------------- |
| `limit`         | number | `20`    | Number of results to return (max `100`)                  |
| `startingAfter` | string | -       | Cursor for fetching results after a specific resource ID |

To paginate through results:

1. Make an initial request without the `startingAfter` parameter
2. If `hasMore` is `true`, use the `id` of the last item in `data` as the `startingAfter` parameter for the next request
3. Repeat until `hasMore` is `false`

```bash
# First page
curl "https://api.makeswift.com/v2/sites/YOUR_SITE_ID/pages?limit=10" \
  -H "x-api-key: your-api-key"

# Next page (using the last page ID from previous response)
curl "https://api.makeswift.com/v2/sites/YOUR_SITE_ID/pages?limit=10&startingAfter=550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: your-api-key"
```

## Rate Limits

The API implements rate limiting per authentication credential (API key or Bearer token) to ensure fair usage and protect service stability. Rate limits may be adjusted over time.

## Errors

The API uses standard HTTP status codes and returns consistent error responses:

| Status | Description                               |
| ------ | ----------------------------------------- |
| `200`  | Success                                   |
| `201`  | Created                                   |
| `400`  | Bad request - check your parameters       |
| `401`  | Unauthorized - invalid or missing API key |
| `403`  | Forbidden - insufficient permissions      |
| `404`  | Not found                                 |
| `409`  | Conflict - resource already exists        |
| `429`  | Too many requests - rate limit exceeded   |

### 400 Bad Request

Returned when the request body or query parameters are invalid.

```json
{
  "object": "error",
  "code": "bad_request",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "name",
      "message": "Name is required"
    }
  ]
}
```

### 401 Unauthorized

Returned when the API key is missing or invalid.

```json
{
  "object": "error",
  "code": "unauthorized",
  "message": "Invalid or missing API key"
}
```

### 403 Forbidden

Returned when the API key is valid but lacks permission to access the resource.

```json
{
  "object": "error",
  "code": "forbidden",
  "message": "You do not have permission to access this resource"
}
```

### 404 Not Found

Returned when the requested resource doesn't exist.

```json
{
  "object": "error",
  "code": "not_found",
  "message": "Site not found"
}
```

### 409 Conflict

Returned when attempting to create a resource that already exists.

```json
{
  "object": "error",
  "code": "conflict",
  "message": "A locale with this code already exists"
}
```

### 429 Too Many Requests

Returned when the rate limit is exceeded.

```json
{
  "object": "error",
  "code": "too_many_requests",
  "message": "Rate limit exceeded"
}
```