# create_workspace

Source: https://modulify.ai/docs/api/workspaces/create-workspace

Creates a new, empty workspace owned by you, on the Free plan and with no AI credits of its own.

- Title: Create a workspace
- Scope: `workspaces:write`
- Access: Makes changes
- Endpoint: `POST /v1/create_workspace`

Billing and credits are per workspace, so the new one starts on the Free plan whatever you pay for elsewhere. It is not your default workspace, though it does become the workspace you are in. On the Free plan a workspace that is not your default is allowed no credits, and any site in it stays locked until it moves to a paid plan.

The name must be 2 to 48 characters. You can own up to 5 workspaces, and past that the call is refused with `You can create up to 5 workspaces!`

It belongs to no workspace, so a token limited to specific workspaces can call it too, although that token cannot reach the new workspace afterwards. Most people asking for a new space for some sites want a folder inside an existing workspace instead, so the tool tells the client to check what you mean before calling it. See [Workspaces](https://modulify.ai/docs/reference/workspaces#create-a-workspace).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/create_workspace`, sending the inputs below as a JSON object. The token needs the `workspaces:write` scope.

It makes changes, so send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
curl -X POST https://api.modulify.ai/v1/create_workspace \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"NAME"}'
```

Over MCP, the same method is the [create_workspace tool](https://modulify.ai/docs/mcp/workspaces/create-workspace).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | What to call it, 2 to 48 characters. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.