Choose who generates the source

Use create_source_site and submit_source when your own agent writes the Astro website. These operations perform no BuildASite model calls and deduct no AI credits. They still consume platform sandbox, browser verification, storage and delivery resources. Existing create_site and edit_site continue to use paid platform generation.

Free plan

Free is permanent: 1 project/domain with 1 website and 1 funnel, 1,000 monthly visitors, and source created with your own external AI. The website and funnel share one project allowance per UTC calendar month. Visitors are browser identities counted with a signed first-party cookie on the delivery hostname. Visiting several children on the same hostname uses the same identity; clearing cookies or using another device/hostname counts separately. Private previews do not count.

After 1,000 visitors, new browsers see a monthly-allowance message; already counted browsers can return. The allowance resets next month. See Plan & usage for the meter and reset date. No automatic paid overage is charged. Upgrade for platform AI or more capacity.

ChatGPT/Claude OAuth setup is documented at /docs/connect-ai. Public discovery listings remain separate from connecting your account. Existing source size and rolling build guards still apply.

Create, edit and review

• Use a workspace key with sites.read and sites.write. Never put the key in website source.
• Create: call create_project with a stable requestId and name, then create_project_child with type website (or funnel and a unique prefix). Read get_site and get_revision for the returned child, then submit_source with its expectedVersion and complete files/dependencies. create_source_site remains a compatibility shortcut; do not use it to create another domain project when you intend to add a funnel to an existing project.
• Edit: call get_site, then get_revision for draftRevisionId. Read all current files and platform resource bindings; reconcile the requested change locally. Call submit_source with expectedVersion, a fresh requestId, message and the COMPLETE replacement files/dependencies maps.
• Poll get_run until committed or a terminal failure. A successful build creates an immutable draft; failed checks preserve the previous draft.
• Call preview_site for the resulting revision. Review it and obtain explicit user approval before publish_site. Publishing is separate and needs sites.publish plus sites.read.

const site = await client.get_site({siteId});
const revision = await client.get_revision({siteId, revisionId: site.draftRevisionId});
// Modify revision.spec.files locally in your own agent.
const run = await client.submit_source({siteId, requestId: crypto.randomUUID(), expectedVersion: site.version, message: "Update the hero headline", files: updatedFiles, dependencies: revision.spec.dependencies});

Source and build limits

• A src/pages/index.astro homepage is required. Only relative src/ and public/ paths are accepted; no traversal or secret files.
• Up to 50 files, 70,000 characters per file, and 90,000 UTF-8 bytes of JSON source; up to 20 dependencies pinned to exact versions. The entire request, including MCP envelope, must fit 110,000 bytes.
• Astro, React and the platform scaffold are provided by the builder. Use import.meta.env.BASE_URL for internal links. Server adapters and backend dependencies are unsupported.
• One external build may be queued/running per workspace, at most 3 submissions per rolling 10 minutes and 20 per rolling 24 hours. Retries of identical admitted requests do not consume another build slot. These are initial operating limits, not a published pricing promise.
• Builds run in an isolated guest with no platform credentials, npm installation scripts disabled and only npm registry network access. Static artifacts and all routes undergo desktop/mobile browser checks before a draft is committed.
• Element overrides can be supplied through the bounded elementOverrides field; omitting it preserves them. Assets, CMS content, resource bindings and typography/media settings are inherited from the authorized base revision. Callers cannot forge build attestations or replace these fields. Removing source files is intentional replacement behavior.

Recover without duplicate builds

Save requestId before submission. After a timeout retry exactly the same inputs. Poll get_run to recover queued dispatch. On version_conflict read the latest source and reconcile; use a new requestId for a different change. Failed builds return a message and preserve the previous saved revision. The external build cannot automatically repair source with a paid model.

Managed resources already in the draft remain available to source edits. Create new managed forms/calendars using create_resource, configure and activate them with save_resource, and read them with list_resources. Source builds load current site-owned resources, including resources created after the previous draft. Browser verification checks the rendered website, but does not prove a new managed conversion journey was completed.