# create_site

Source: https://modulify.ai/docs/api/sites/create-site

Creates a new site in a workspace and starts building it from your prompt straight away.

- Title: Create a site from a prompt
- Scope: `sites:create`
- Access: Makes changes
- Endpoint: `POST /v1/create_site`

This spends AI credits from the workspace. Describe the whole site you want in the prompt, the way you would brief a developer.

It returns the new site as `project` and a `jobId`, and you follow the build by polling `get_job` with that `jobId`, which needs `chat:read`. Creating a site provisions real infrastructure, so it can take a while.

A refusal comes back as an error carrying the reason: `credits-limit-reached` when the workspace has no AI credits left, or `site-limit-reached` with the current count and limit when the plan has no site slot left. Archived sites count toward that limit too.

To rebuild an existing website instead of starting from nothing, pass `importSource` with `SourceUrl` set to the page to work from. The prompt still applies, so say what should change in the rebuild rather than repeating the address. To build from a GitHub repository, set `Source` to `github` with `Owner` and `Repo`, and optionally `Branch`, keeping the repository address in `SourceUrl`. A private repository is read only when its GitHub account is connected and verified in the same workspace, and anything else is refused as unreadable, exactly like a repository that does not exist, as [Import from GitHub](https://modulify.ai/docs/build/import-from-github) describes. See [Create a project](https://modulify.ai/docs/projects/create-a-project).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/create_site`, sending the inputs below as a JSON object. The token needs the `sites:create` 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_site \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","prompt":"PROMPT"}'
```

Over MCP, the same method is the [create_site tool](https://modulify.ai/docs/mcp/sites/create-site).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace to create the site in. |
| `prompt` | string | Yes | What the site should be. Be specific about pages, content and style, in at most 500,000 characters. |
| `mode` | string | No | `build`, where the agent builds the site straight away, or `plan`, where it proposes a plan for you to approve first. Defaults to `build`, and any other value is refused. |
| `importSource` | object | No | The existing website to rebuild. `SourceUrl` is the page to work from, and without it the whole import is ignored and you get a plain prompt build. `Source` names the platform, one of `shopify`, `webflow`, `wordpress`, `github` or `unknown`, `Name` is the business name, `Origin` is the site root when `SourceUrl` is a deeper page, and `Owner`, `Repo` and `Branch` name a GitHub repository. |

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