> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makeswift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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

export const ReadinessBadge = ({type}) => {
  const validTags = ["beta", "alpha", "experimental"];
  const tagText = type?.trim().toLowerCase();
  if (!tagText || !validTags.includes(tagText)) return null;
  useEffect(() => {
    const titleElement = document.querySelector("#page-title, .page-title, h1");
    if (!titleElement) return;
    if (titleElement.querySelector(".badge")) return;
    const badge = document.createElement("span");
    badge.className = `badge ${tagText}-badge`;
    badge.textContent = tagText;
    badge.style.transform = "translateY(-3px)";
    titleElement.appendChild(badge);
  }, []);
  return null;
};

<ReadinessBadge type="beta" />

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 theme={null}
curl https://api.makeswift.com/v2/sites \
  -H "x-api-key: your-api-key"
```

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

## Resources

| Resource                                                 | Description                                       |
| -------------------------------------------------------- | ------------------------------------------------- |
| [Sites](/developer/reference/api/sites/list-sites)       | Create, read, update, delete, and duplicate sites |
| [Locales](/developer/reference/api/locales/list-locales) | Configure localization settings                   |
| [Pages](/developer/reference/api/pages/list-pages)       | Manage pages within a site                        |
| [Routes](/developer/reference/api/routes/list-routes)    | Define external routes for your site              |

## Response format

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

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

List endpoints return paginated results:

```json theme={null}
{
  "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 theme={null}
# 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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "object": "error",
  "code": "not_found",
  "message": "Site not found"
}
```

### 409 Conflict

Returned when attempting to create a resource that already exists.

```json theme={null}
{
  "object": "error",
  "code": "conflict",
  "message": "A page with this path already exists"
}
```

### 429 Too Many Requests

Returned when the rate limit is exceeded.

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