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

The attach response returns the records you publish to verify ownership (ssl_validation + ownership_verification), the dns_target to point a CNAME at, an is_apex flag (with dns_note guidance for root domains), and two independent statuses:

{
  "data": {
    "hostname": "app.example.com",
    "cert_status": "pending_validation",
    "ownership_status": "pending",
    "dns_target": "abcd1234-marketing.app.amba.host",
    "is_apex": false,
    "dns_note": null,
    "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. For a subdomain, add a CNAME. For a root (apex) domain (is_apex: true), point the root at the target if your DNS provider flattens CNAME-at-root; otherwise use a subdomain until A-record apex support ships (see dns_note on the response).
3. Wait for both statuses 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.

Your domain is live — and the certificate renews automatically — only once both statuses read active. Poll the list endpoint (or amba_sites_list_domains), or call refresh-cert to force a re-check.

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.