Domains

Amba can buy a domain for you and connect it to one of your sites in a single flow — you never touch DNS. Search for an available name, see the price, confirm, and Amba registers the domain, points it at your site, and provisions a managed TLS certificate automatically.

This is the fastest path from "I need a domain" to a live site on it. If you already own a domain and just want to attach it, use the custom-domain flow on Sites instead — that path has you point a DNS record yourself.

The flow

1. Search for available names (free).
2. Check the exact price + availability of the ones you like (free).
3. Buy — Amba shows the cost, you confirm, and Amba:
   • registers the domain,
   • connects it to your chosen site,
   • publishes the DNS records for you, and
   • starts issuing a TLS certificate.

When the certificate finishes issuing (usually a minute or two) your site is live on the new domain with HTTPS — no DNS configuration on your side.

CLI

# Search for available names + prices (free)
amba domains search getunbury
 
# Price specific names (free)
amba domains check getunbury.com getunbury.app
 
# Buy one + connect it to a site. Shows the cost and asks to confirm.
amba domains buy getunbury.com --site marketing
 
# Skip the interactive confirmation (e.g. in a script) — still only buys
# if purchasing is enabled for your account.
amba domains buy getunbury.com --site marketing --yes
 
# Domains you've bought through Amba
amba domains list

Options on buy:

• --site <name> (required) — the site to connect the domain to.
• --years <n> — registration length in years (default 1).
• --no-privacy — disable WHOIS privacy (on by default).
• --no-auto-renew — disable auto-renew (on by default).
• --yes — skip the interactive cost confirmation prompt.

MCP tools

Agents can run the whole flow through MCP:

• amba_domains_search — find available domains for a query (free).
• amba_domains_check — authoritative availability + price for specific domains (free).
• amba_domains_purchase — buy + connect a domain to a site.
• amba_domains_list — list domains purchased through Amba.
• amba_domains_email_enable / amba_domains_email_status — enable and inspect inbound routing.
• amba_domains_email_destinations_add / list / get — start and poll mailbox verification.
• amba_domains_email_forwards_set / list / delete — manage literal forwards such as support@example.com → owner@gmail.com.
• amba_domains_email_catch_all_set / get — forward every unmatched address to one mailbox.

amba_domains_purchase is two-step for safety: the first call (without confirm) returns a quote with the price and confirmation_required: true and charges nothing. Surface the cost to the user, then call again with confirm: true and accept_price_usd set to the quoted price to execute.

Email forwarding

Domains purchased through Amba can receive email without a separate mailbox server. Inbound messages can be forwarded from named addresses or a catch-all to an existing external mailbox.

1. amba_domains_email_enable
2. amba_domains_email_destinations_add
3. The mailbox owner clicks the verification email.
4. Poll amba_domains_email_destinations_get until status is verified.
5. Call amba_domains_email_forwards_set or amba_domains_email_catch_all_set.

The forward/catch-all tools combine these steps when possible. If the destination is new, they return action_required: true; repeat the same set call after verification to activate the rule.

Email forwarding is inbound-only. It does not create an inbox or provide SMTP credentials for sending mail as the domain.

REST

All endpoints are project-scoped and Bearer-authed (/v1/admin/...).

Search (free)

GET /v1/admin/projects/{project_id}/domains/search?q=getunbury&limit=20

{
  "data": [
    {
      "domain": "getunbury.com",
      "available": true,
      "price_usd": 10.44,
      "currency": "USD",
      "premium": false
    },
    {
      "domain": "getunbury.app",
      "available": true,
      "price_usd": 12.0,
      "currency": "USD",
      "premium": false
    }
  ]
}

Check (free)

POST /v1/admin/projects/{project_id}/domains/check
{ "domains": ["getunbury.com", "getunbury.app"] }

Each result adds a supported flag — false means that extension can't be registered through Amba yet.

Purchase

POST /v1/admin/projects/{project_id}/domains/purchase
{ "domain": "getunbury.com", "site": "marketing" }

site is optional — include it to auto-connect the domain to that site, or omit it to register the domain only and connect it to a site later.

The first call (no confirm) returns a quote and charges nothing:

{
  "data": {
    "domain": "getunbury.com",
    "site": "marketing",
    "executed": false,
    "confirmation_required": true,
    "price_usd": 10.44,
    "currency": "USD",
    "message": "Confirm to purchase: re-submit with `confirm: true` and `accept_price_usd` set to the price above."
  }
}

To execute, re-submit with the price acknowledgement and confirmation:

POST /v1/admin/projects/{project_id}/domains/purchase
{
  "domain": "getunbury.com",
  "site": "marketing",
  "confirm": true,
  "accept_price_usd": 10.44,
  "auto_renew": true,
  "privacy": true,
  "years": 1
}

On success:

{
  "data": {
    "domain": "getunbury.com",
    "site": "marketing",
    "executed": true,
    "registered": true,
    "provisioned": true,
    "dns_autoconfigured": true,
    "cert_status": "pending_validation",
    "ownership_status": "pending",
    "route_status": "active",
    "kv_status": "active",
    "dns_status": "active",
    "hostname_live": false,
    "public_url": "https://getunbury.com",
    "message": "Domain registered and the DNS binding was created. Hostname serving planes are still converging; poll hostname_live before treating the URL as live."
  }
}

A confirmed purchase also returns an operation_id (when the registrar settles asynchronously). Poll it to a terminal succeeded / failed instead of guessing — see Operations:

GET /v1/admin/projects/{project_id}/operations/{operation_id}

Registration, binding creation, hostname activation, certificate deployment, Worker routing, host KV, and managed DNS are separate states. provisioned: true means the binding was created; it does not mean the public URL is reachable. Treat the hostname as ready only when server-derived hostname_live: true. That requires active ownership_status, cert_status, route_status, kv_status, and dns_status for a purchased domain. The purchase response's live field remains the payment/registration execution gate and is not a reachability signal.

The confirmed purchase 201 includes the persisted route_status, kv_status, and dns_status values shown above. Clients should display those values directly rather than substituting pending when provider activation is the only unfinished plane.

Track registration and authoritative binding status with:

GET /v1/admin/projects/{project_id}/domains            # all your domains
GET /v1/admin/projects/{project_id}/domains/{domain}   # one domain's status

Both GET endpoints re-poll the linked Site binding and expose the apex plus any www alias. A pending hostname can therefore transition to hostname_live: true through normal polling. Use the Site domain refresh endpoint when an operator needs to force repair of DNS, Worker route, or KV.

Email routing

POST   /v1/admin/projects/{project_id}/domains/{domain}/email/enable
GET    /v1/admin/projects/{project_id}/domains/{domain}/email
POST   /v1/admin/projects/{project_id}/domains/{domain}/email/destinations
GET    /v1/admin/projects/{project_id}/domains/{domain}/email/destinations/{destination_id}
POST   /v1/admin/projects/{project_id}/domains/{domain}/email/forwards
GET    /v1/admin/projects/{project_id}/domains/{domain}/email/forwards
DELETE /v1/admin/projects/{project_id}/domains/{domain}/email/forwards/{forward_id}
PUT    /v1/admin/projects/{project_id}/domains/{domain}/email/catch-all
GET    /v1/admin/projects/{project_id}/domains/{domain}/email/catch-all

Errors

• 409 DOMAIN_UNAVAILABLE — the name isn't available to register.
• 409 DOMAIN_EXTENSION_UNSUPPORTED — that extension can't be registered through Amba yet.
• 409 PRICE_CHANGED — the price moved since you were quoted; re-check and re-confirm with the new price.
• 503 DOMAINS_NOT_CONFIGURED — domain purchasing isn't available on this deployment.