Create a site from a prompt

create_site

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

POST /v1/create_siteScopesites:createMakes changes

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 describes. See 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 header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

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.

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 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 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 explains every status code a call can answer with.