# Site and deployment tools | answer.cloud Docs

> Canonical source: [Site and deployment tools | answer.cloud Docs](https://www.answer.cloud/docs/reference/deploy-tools/)

Use current site and deployment tool arguments, returned fields, destination rules, upload limits, pipeline statuses, and recovery behavior.

reference

Site and deployment tools

Use current site and deployment tool arguments, returned fields, destination rules, upload limits, pipeline statuses, and recovery behavior.

Reviewed November 1, 2026

These tools create standalone sites and publish static artifacts. All tools accept `organization_id` when organization selection is required. Deploy IDs are numeric record identifiers; sequences are site-local release numbers. Keep both with the site slug.

## Site discovery and preparation

| Tool           | Required arguments                     | Optional arguments               | Returns                                                                                   |
|----------------|--------------------------------------|--------------------------------|-------------------------------------------------------------------------------------------|
| `list_sites`   | None beyond organization selection   | —                              | `sites[]`.                                                                                |
| `prepare_site` | `email` string, `organization_name` string | `description` string, `goal` string | `organization_id`, `organization_name`, `site_slug`, `site_url`, `environment`, `prompt`, `next`. |
| `create_site`  | `slug` string                        | `name` string                   | Site view.                                                                               |

`prepare_site` requires a personal OAuth connection or personal MCP token and a matching account email. Limits are email 254 characters, organization name 120, description 5,000, and goal 1,000. It prepares a first-site reservation; it does not sign someone into another account by email, rename an established workspace, or replace a launched site. `create_site` requires eligible free hosting signup or existing card access and reuses an owned slug. Slugs are lowercase DNS labels with letters, digits, and hyphens; reserved hostnames are unavailable.

Site views include `slug`, `name`, `kind`, `url`, `custom_domain`, `status`, `pages_used`, `pages_limit`, `current_deploy`, `release_workflow`, and `widget`. `current_deploy` contains sequence and live time; `release_workflow` includes staging/production URLs and deployment pointers.

## Upload and inspect an artifact

| Tool           | Required arguments                   | Optional arguments             | Returns                                                                                   |
|----------------|------------------------------------|------------------------------|-------------------------------------------------------------------------------------------|
| `start_deploy` | `site_slug` string, `environment` enum | `git_metadata` object          | `deploy_id`, `sequence`, `environment`, `upload_url`, `expires_at`, `max_bytes`, `upload_command`, `next`, remaining quota. |
| `finalize_deploy` | `deploy_id` integer               | `artifact_sha256` string       | `deploy_id`, `status`, `environment`.                                                    |
| `deploy_files` | `site_slug`, `environment`, `files[]` | `message` string               | `deploy_id`, `status`, `environment`, remaining quota.                                  |
| `get_deploy`   | `deploy_id` integer                 | —                            | Detailed pipeline status.                                                                 |
| `list_deploys` | `site_slug` string                  | `commit_sha` full Git hash     | `deploys[]`, up to seven recent matches.                                                 |
| `rollback`     | `site_slug`, `to_sequence` integer | `environment`: `staging` or `production`, default production | `site`, `environment`, `current_sequence`, `live_url`.                                   |

`environment` for new deploys is explicitly required: `staging`, `production`, or `both`. Staging and both require the release workflow. Production and both require an active custom domain when that workflow is enabled. Companions support production only. A guest first launch already targets its reserved site's production destination.

```json
{
  "site_slug": "example-site",
  "environment": "staging",
  "git_metadata": {
    "base_sha": "0123456789abcdef0123456789abcdef01234567",
    "branch": "docs-update",
    "dirty": true,
    "trigger": "mcp"
  }
}
```

Send that object to `start_deploy`. Package the contents of the built output with `index.html` at the ZIP root and all required assets/private CMS files. Upload binary bytes to the exact private signed URL before expiry, then finalize the returned ID. Upload URLs last 900 seconds; use returned `max_bytes` as the artifact ceiling.

`git_metadata` permits `sha`, `base_sha`, `branch`, `message`, `dirty`, and `trigger`. Hashes must be full Git hashes. Dirty source records a base hash rather than claiming an exact commit; string metadata is bounded to 200 characters.

## Inline artifacts

Each `files` item contains required string fields `path` and `content_base64`. There must be 1–200 files and no more than 512,000 decoded bytes total.

**`deploy_files` creates a fresh artifact from the supplied files. It does not merge a patch with the previous deployment.** Include every required file for the tiny site, or use the full ZIP workflow. Omitting an asset can remove it from the new release.

## Status and recovery

`get_deploy` returns `deploy_id`, `sequence`, timestamps, `status`, `git`, `warnings`, `pages_ingested`, `pages_skipped`, `error`, `environment`, staging/production pointer flags, and `cms_collections`. A live result adds `live_url`, `live_urls`, and `live_at`. In-progress results include `retry_after_seconds`; normally three seconds.

For a linked repository with GitHub enabled, successful uploads save public deployed files to the linked branch after publication. The completed save appears in `git`; `list_deploys` can match its full `commit_sha`. A `github_commit_failed` warning means the site remains live but its GitHub save failed. Check the connection and repository access, then deploy again. See [automatic commits after uploads](https://www.answer.cloud/docs/hosting/github/#automatic-commits-after-uploads).

The pipeline can progress through `uploading`, `queued`, `extracting`, `embedding`, `syncing_cms`, `generating_aeo`, `publishing_cms`, and `live`. It can fail or later be marked `rolled_back`. Do not re-finalize a deployment already processing. Uploading or failed records with a usable uploaded artifact can be finalized again; inspect the current state first.

`no_artifact` means the upload is missing. `too_large` at finalization deletes the oversized upload. `invalid_state` means inspect before retrying. Read warnings such as `spa_shell`, skipped pages, `cms_path_collision`, and social-image problems even when status is live.

Normal deploy-creating calls return `deploys_remaining_today`; guest calls return `deploys_remaining`. Polling and CMS publishing do not consume deployment starts. Rollback uses a previously live/rolled-back sequence and rematerializes published CMS content; verify restored pages rather than assuming content is a historical CMS snapshot.

See [deployment recovery](https://www.answer.cloud/docs/troubleshooting/deployments/) and [release configuration](https://www.answer.cloud/docs/reference/site-configuration-tools/).