Sites

Amba hosts static sites — marketing pages, docs, SPAs, anything that's a bundle of files. Deploy a directory and Amba serves it at https://{slug}.app.amba.host with a managed TLS certificate. Attach a custom domain when you're ready, and roll back to any previous deployment in one call. Every deployment is immutable, so a rollback is just a pointer flip — no rebuild.

The fastest paths are the CLI (amba sites deploy ./dist) and the amba_sites_* MCP tools. The REST surface below is what both wrap.

Concepts

• Site — a named container for deployments. The name must match ^[a-z][a-z0-9_-]{0,49}$ and becomes part of the public URL. Public URL: https://{slug}.app.amba.host, where slug is the first 8 characters of your project id plus the site name.
• Deployment — one immutable upload of files. The current deployment serves all traffic; older ones are retained for rollback.
• Custom domain — your own hostname (e.g. app.example.com) bound to the site, with a TLS certificate Amba provisions and renews for you.

Deploy

The CLI bundles a directory and ships it in one command:

amba sites deploy ./dist --name marketing

From an agent, amba_sites_deploy creates the site (if needed) and uploads the files in a single tool call — pass project_id, name, and a files object mapping each relative path to its content.

Under the hood, deploy is two REST calls — register the site, then upload the bundle as multipart form data (one part per file, keyed by relative path):

A successful deploy returns the canonical URL plus file/byte counts:

{
  "data": {
    "deployment_id": "…",
    "site_name": "marketing",
    "url": "https://abcd1234-marketing.app.amba.host",
    "deployed_at": "2026-05-27T10:00:00.000Z",
    "status": "active",
    "file_count": 12,
    "total_bytes": 348201
  }
}

The per-file cap is 25 MiB. A failed upload leaves your live site untouched — the new deployment is only made current after all files land.

Custom domains

Bind your own hostname, then publish the DNS records Amba returns. Amba registers the hostname and provisions and renews the certificate for you — you don't need any third-party credentials.

amba sites domain add marketing app.example.com

Lifecycle fields are read-only. The former PATCH .../domains/:hostname surface returns 405 LIFECYCLE_READ_ONLY; clients cannot declare a hostname active. Use the refresh endpoint and wait for the server-derived readiness field instead.

The attach response returns the records you publish to verify ownership (ssl_validation + ownership_verification), the dns_target to point a CNAME at, a Public-Suffix-List-derived is_apex flag, an unconditional dns_note record-type warning, and independent provider and serving-plane statuses:

{
  "data": {
    "hostname": "app.example.com",
    "cert_status": "pending_validation",
    "ownership_status": "pending",
    "route_status": "active",
    "kv_status": "active",
    "dns_managed": false,
    "dns_status": "not_required",
    "live": false,
    "dns_target": "abcd1234-marketing.app.amba.host",
    "dns_record_type": "CNAME",
    "is_apex": false,
    "dns_note": "Publish a real CNAME; ALIAS, ANAME, and copied A/AAAA records do not activate standard custom-hostname routing.",
    "ssl_validation": [
      {
        "txt_name": "_acme-challenge.app.example.com",
        "txt_value": "<token>"
      }
    ],
    "ownership_verification": {
      "type": "txt",
      "name": "_amba-challenge.app.example.com",
      "value": "<token>"
    }
  }
}

The flow is:

1. Publish the verification records. Add the ssl_validation TXT record(s) and the ownership_verification TXT record at your DNS provider. If ssl_validation is empty on the immediate response, it populates shortly — re-fetch the live records via the refresh-cert endpoint or amba_sites_list_domains.
2. Point DNS at dns_target. Publish the returned dns_record_type exactly; the real-CNAME warning is returned for every hostname, not only apexes. For a root domain (is_apex: true), provider-native CNAME-at-root flattening is valid only when the provider stores a real CNAME. Do not substitute an ALIAS, ANAME, or resolved A/AAAA value. Use a subdomain if your DNS provider cannot store an apex CNAME (see dns_note on the response).
3. Wait for every required plane to reach active. ownership_status (pending → active) confirms you control the hostname; cert_status (pending_validation → pending_issuance → pending_deployment → active) tracks the TLS certificate. route_status and kv_status confirm the edge route and host-to-site mapping. Purchased domains also require dns_status: active; externally managed DNS reports not_required.

Your domain is live — and the certificate renews automatically — only once the server-derived live field is true. A successful TLS handshake, or even active certificate and ownership states together, do not prove the Worker route and host KV are ready. Poll the list endpoint (or amba_sites_list_domains), or call refresh-cert to force all-plane repair. route_status, kv_status, and managed dns_status errors are retryable and remain eligible for bounded CLI polling/refresh. Provider-terminal cert_status or ownership_status errors require re-attachment.

Rollback

Every deployment is immutable and kept on file. To revert, point the site back at a previous deployment_id (find ids via amba_sites_get or GET /sites/:name):

curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/sites/marketing/rollback' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "deployment_id": "…" }'

The flip is atomic — the next request serves the prior bundle. You can't roll back to a failed deployment, and rolling back to the already-current deployment is rejected.

Pause and delete

PATCH .../sites/:name with { "status": "disabled" } stops the site (and its custom domains) from serving without losing the deployment history; set it back to active to resume.

DELETE .../sites/:name?confirm=<name> tears everything down — custom hostnames are unbound, every deployment's files are removed, and the site row is archived. The ?confirm=<name> guard is required; the CLI and MCP tool set it for you. The response reports what was cleaned up:

{
  "data": {
    "name": "marketing",
    "deleted": true,
    "cascade": { "domains_removed": 1, "objects_removed": 12 }
  }
}

MCP tools

See the CLI reference for the full amba sites command set.