# Domains

> Every app gets <slug>.vibiz.app. Buy a domain of its own from your credits, registered to you, and use it (or app., api.…) on any of your projects with no DNS to set.

Every app already answers at `https://<slug>.vibiz.app`, free, for as long as it exists. When the business wants a name of its own, buy one here: it is paid from the account's credits, registered to the owner, and belongs to the account: use it, or any name under it (`app.`, `api.`…), on any of your projects in one click, with HTTPS and no DNS to set. A domain you already own elsewhere is connected instead ([Hosting ▸ Your own domain](https://thelastapi.dev/docs/hosting#your-own-domain)).

## Buying one

```bash
vibiz domains search sellshelf          # names across endings, with prices
vibiz domains buy sellshelf.app         # full-access key: shows the price, the balance after, and asks
vibiz domains owned                     # what the account bought: expiry, auto-renew, where each is used
```

In the console: **Domains** in the main menu (search, pick one, choose the project it serves on or none for now, confirm), or the project ▸ **Domains** ▸ **Buy a domain**.

1. **Search** a name (`sellshelf`) or an exact domain (`sellshelf.app`). Each result shows the price for the first year and the renewal price a year, in USD.
2. **Quote** one: the price, your balance after, and whether your saved owner details cover it.
3. **Confirm** (the owner). The price is taken from your credits, the registration is placed, and within a minute or two the domain is `active` and serves the project, `www` included.

- **Prices** are in USD cents and are the full price: nothing else is added. Premium names (priced higher by the registry) need an explicit confirmation.
- **The price you saw is the price you pay.** A buy carries `expected_price_cents`; if the price moved since, nothing is charged and the answer (`409`, `reason: price_changed`) carries a new quote to confirm.
- **Not enough credits**: `402 payment_required` with the Billing link in `next_step`. Add credits and buy again.
- **If the registration fails**, the credits go back to your balance at once (a `domain_refund` line in Billing ▸ History).
- On the Billing history a purchase is a `domain` line: `Domain sellshelf.app (1 year)`.

## Use it on any project

A bought domain is the account's, not one project's. Any of your projects can use it, or any name under it, in one call: we hold its DNS (it is on our nameservers), so there is never a record to set.

```bash
vibiz domains use sellshelf.app --project shop                  # the domain itself (and www) on "shop"
vibiz domains use sellshelf.app --project docs --name docs      # docs.sellshelf.app on "docs"
vibiz domains use api.sellshelf.app --project api               # the full name works too
vibiz domains move sellshelf.app --to shop-v2                   # full-access key: off shop, onto shop-v2
vibiz domains owned                                             # each domain: the projects and names using it
```

- **On thelastapi hosting** the name is attached to the app and goes live by itself with HTTPS, usually within a minute or two. Its status is never `pending_dns`: `records_to_set` stays empty and `dns_by_vibiz` is `true`. If the host ever asks for a record (a routing record, an ownership TXT), we write it into the domain's zone ourselves.
- **For an app on another host** (a project without thelastapi hosting, or `hosting: "elsewhere"`), sign-in and analytics trust the name at once. Pass `points_to` (the other host's address: a host name like `cname.yourhost.com`, or an IP) and we write the record in the domain's DNS: a `CNAME` for a name under it, an `ALIAS` (or `A` for an IP) for the domain itself. `vibiz domains point app.sellshelf.app cname.yourhost.com` changes it; `none` clears it. Moving the name away or removing it removes that record.
- **A name serves one project at a time.** Using one another project has answers `409 conflict` with `reason: in_use`, `details.used_on` (the project) and the `vibiz domains move …` to run. `move` (full-access keys, like removing a domain) takes it off the old project's hosting, with its `www`, and puts it on the new one, again with no DNS. `from_project_id` is an optional check.
- **Names are**: nothing (or `@`) for the domain itself, a prefix (`app`), or the full name (`app.sellshelf.app`, `a.b.sellshelf.app`).
- Typing a name under a bought domain in a project's **Add a domain** (or `vibiz domains add app.sellshelf.app`) works the same way: recognized as bought, trusted, no DNS.
- Only this account can use its bought domains: another account adding a name under one is refused (`409 domain_taken`).
- **Moving the business to a new domain** (`seoulsim.xyz` → `seoulsim.com`): add the new one, wait until it's live, then `vibiz domains redirect seoulsim.xyz seoulsim.com`. Every URL on the old domain answers a permanent redirect to the same path on the new one, so search engines carry the old pages over, and the new one becomes the project's main address. `none` stops it. See [Hosting ▸ Moving to a new domain](https://thelastapi.dev/docs/hosting#moving-to-a-new-domain).
- In the console: **Domains** ▸ each domain shows where it is used, with **Use on a project** (pick the project, the domain itself or a prefix) and **Move**; a project's **Domains** page lists your bought domains as one-click choices.

## Owner details

A domain is legally registered to a real person or company: the **domain owner**. Their details (name, email, phone, postal address, optionally the company) are entered once, on the first purchase, and saved for the account (encrypted at rest); later purchases use them by themselves, and the confirmation shows "Registered to: Ann Smith, San Francisco, US". Personal details are hidden from the public WHOIS where the domain ending allows it.

- `country` is the two-letter ISO code (`ES` for Spain, `GB` for the United Kingdom, `US`), in any case; the console picks it from a list. `phone` is international, `+` and the country code (`+34612345678`); spaces and dashes are fine.
- They are checked before anything is ordered or charged, saved details too. A wrong one is `400 invalid_request` naming the field in `details.field` (`contact.country`) and each problem in `details.problems`, with how to fix it: `Country: “SP” isn't a country code. Spain is ES.` If the registry still refuses a detail, the answer names that field the same way, and nothing is charged.
- Some endings ask for more (`.us`: a nexus category; `.ca`: a legal type). Only those extra fields are asked for, and they are saved too: the quote's `owner_details.fields_needed` lists them.
- Change them in the console (**Domains ▸ Owner details**), with `vibiz domains owner --input '<json>'`, or `PUT /v1/domains/owner`. Changes apply to domains bought from then on.
- Only an owner can see or change them. Agents never fill them in.

## Confirming the owner

ICANN, which oversees domain names, requires a new domain's owner contact details to be confirmed within 15 days of registration; without it the registry suspends the domain. thelastapi handles the request for you: the registry writes to a private contact address we keep for the domain (your name, address and phone stay on the registration; you remain the legal owner), and the account's owners get one email from thelastapi, **Confirm your domain sellshelf.app**, with a link to the console. Press **Confirm** there and it is done.

- Each owned domain carries `contact_verification`: `status` (`pending`, `verified`, or `unknown` before the registry has answered), `verify_by`, and `can_confirm` (the request arrived and one click confirms it). The console shows "Confirm by <date>" on the domain until it is confirmed.
- Reminders go out 7, 3 and 1 day(s) before `verify_by`. thelastapi checks with the registry about once a day; **Check now** (or `POST /v1/domains/:domain/contact-verification/check`) asks at once.
- If the request hasn't arrived, `next_step` says so: write to support@vibiz.ai and we finish it before the deadline.
- Domains bought before this was in place were registered with the owner's own email: the registry wrote to that address, so open its message and follow the link. The console still shows where it stands.

## Email at the domain

Want `hello@` your new domain in the inbox you already use? After buying, press **Set up email** (or Domains ▸ Email forwarding): thelastapi sets the domain's mail records for you, and forwards each address you choose, "via thelastapi". See [Email ▸ Forwarding](https://thelastapi.dev/docs/email#forwarding-helloyourcompanycom-to-your-inbox).

## DNS records

We host the DNS of every domain bought here, so when another service asks you to add a record (a TXT to verify the domain, like an OpenAI business profile or Google Search Console; a CNAME for a help desk; MX for another mail provider), add it here: no other tool, no other account.

```bash
vibiz domains records canetada.app                        # every record; the ones we keep say "managed"
vibiz domains records add canetada.app TXT openai-business-profile "openai-business-profile=…"
vibiz domains records add canetada.app MX @ mx.mailhost.com --priority 10 --ttl 3600
vibiz domains records remove canetada.app <id>            # a managed one needs --force
```

In the console: **Domains** ▸ the domain ▸ **DNS records** (a list, and a form to add one).

- **Types:** `A` (an IPv4 address), `AAAA` (IPv6), `CNAME` (another host name), `MX` (a mail server, with `priority`), `TXT` (up to 2048 characters) and `CAA` (`0 issue "letsencrypt.org"`).
- **Names are relative to the domain:** `openai-business-profile` is `openai-business-profile.canetada.app`; `@` (or `""`) is the domain itself. A full name under the domain works too.
- **A CNAME** can't be on the domain itself (DNS doesn't allow it at the apex: use an `A` record, or use the domain on a project with `points_to`), and can't share its name with any other record.
- **Adding is idempotent:** the same type, name and value already there comes back (`200`, `created: false`), never a second copy.
- **Managed records** are the ones we keep: `managed_by: "hosting"` (where a name a project uses points), `"email"` (forwarding, the inbox and sending: MX, SPF, DKIM, DMARC) and `"default"` (the DNS defaults, like the CAA that lets HTTPS certificates be issued). Leave them: change hosting with `vibiz domains point` / `move`, and email by turning it off. Removing one answers `409 managed_record` with what to run instead, unless you pass `force`.
- **Who:** any key on the account reads the records; adding and removing need a full-access key (a Limited key gets `403 owner_only` with the console link).
- New records usually answer within a minute or two: `dig +short TXT openai-business-profile.canetada.app` checks.
- A domain connected from elsewhere (`vibiz domains add … --elsewhere`) keeps its DNS where it was bought: add its records there.

## Renewals

Domains are registered for a year (up to 10 with `--years`). **Auto-renew is on**: about 30 days before expiry the renewal price is taken from your credits and the domain renewed. If the credits are short, the account's owners are emailed and it is tried again every day; add credits and it renews by itself. Turn auto-renew off per domain (`vibiz domains auto-renew sellshelf.app off`) to let it lapse, or renew early with `vibiz domains renew sellshelf.app`.

## Moving a domain out

The domain is yours. `vibiz domains transfer-code sellshelf.app` (full-access key, or the console) gives the code another registrar asks for. Registries lock a domain for 60 days after it is registered or moved.

## Agents

Agents may search and quote. By default buying and renewing are the owner's: a quote carries `buy_url`, the console page where the owner confirms, and an agent's buy answers `403 owner_only` with the same link in `details.console_url`.

The owner can let agents and the CLI buy and renew domains themselves, up to a price per domain: console ▸ Billing ▸ *Domains bought by agents*, or `PATCH /v1/billing {"agent_domain_limit_cents": 3000}` (full-access key; `null` turns it off). Then a quote says `can_buy: true` and `agent_limit_cents`, and a Limited key buys with the owner details the owner saved (it can never send its own). Over the limit: `403 over_agent_limit` with the confirm link. Premium names always need the owner. Auto-renew, the transfer code and the owner details stay the owner's.

A bought domain is trusted for sign-in at once (we hold its DNS), and so is any name under it a project adds, with no TXT record to set.

From MCP: `vibiz_dns_records` (`list`, `add`, `remove`) for a bought domain's DNS records (adding and removing are an owner's; never remove a `managed` one unless the user asked). `vibiz_buy_domain` (`search`, `quote`, `buy`, `owned`, `use`, `move`, `point`): search first, tell the user the price, then `buy` when the quote's `can_buy` is true, or send the owner the link; `use` puts a bought domain (or `app.<domain>`) on any project with no DNS, `move` takes it to another. Any key may `use` and `point`; `move` is an owner's. From the CLI: `vibiz domains buy <domain>` buys when allowed and prints the link otherwise.

## Over HTTP

| Route | Who | |
| --- | --- | --- |
| `GET /v1/domains/search?q=sellshelf` | any key | `data[]`: `domain`, `available`, `premium`, `price_cents`, `renewal_price_cents`, `buy_url` |
| `GET /v1/domains/quote?domain=&years=&project_id=` | any key | the price, `balance_after_cents`, `enough_credits`, `owner_details`, `buy_url`, `next_step` |
| `POST /v1/projects/:id/domains/buy` | owner | `{ domain, years?, expected_price_cents, confirm_premium?, contact?, save_contact?, additional? }` → `202` the owned domain (`registering`, then `active`) |
| `POST /v1/domains/buy` | owner | the same body plus `project_id?`: none keeps it for the account, to use later |
| `GET /v1/domains` · `GET /v1/domains/:domain` | any key | owned domains: `status`, `expires_at`, `auto_renew`, `renewal_price_cents`, `registered_to`, `used_on` (`project_id`, `project_name`, `name`, `hosting`…), `contact_verification`, `last_order` |
| `POST /v1/domains/:domain/use` | any key | `{ project_id, name?, hosting?, points_to? }` → `domain_use`: `project_domain` (no `records_to_set`), `owned`, `next_step` |
| `POST /v1/domains/:domain/move` | owner | `{ to_project_id, name?, from_project_id?, hosting?, points_to? }` → `domain_use` with `moved_from` |
| `POST /v1/domains/:domain/point` | any key | `{ name?, points_to, project_id? }`: where a name used by an app elsewhere points (`null` clears) |
| `GET /v1/domains/:domain/records` | any key | `data[]`: `id`, `type`, `name` (relative, `''` the domain itself), `fqdn`, `value`, `ttl`, `priority`, `managed`, `managed_by` |
| `POST /v1/domains/:domain/records` | owner | `{ type, name, value, ttl?, priority? }` → `201` the record (`200`, `created: false`, when it is already there) |
| `DELETE /v1/domains/:domain/records/:id` | owner | removes it; a `managed` one needs `?force=1` |
| `POST /v1/domains/:domain/contact-verification/confirm` | owner | confirm the owner's contact details (when `can_confirm`) |
| `POST /v1/domains/:domain/contact-verification/check` | any key | ask the registry now |
| `PATCH /v1/domains/:domain` | owner | `{ auto_renew }` |
| `POST /v1/domains/:domain/renew` | owner | `{ years?, expected_price_cents }` |
| `POST /v1/domains/:domain/auth-code` | owner | the transfer code |
| `GET /v1/domains/owner` · `PUT /v1/domains/owner` | owner | the owner details `{ contact }` |

## Errors

| Code | Status | When | Next step |
| --- | --- | --- | --- |
| `payment_required` | 402 | the balance doesn't cover the price | add credits (`next_step`), buy again |
| `conflict` (`price_changed`) | 409 | the price moved since the quote | confirm `details.quote.price_cents` |
| `invalid_request` (`owner_details_required`) | 400 | no owner details saved yet | the owner fills them in at `details.console_url` |
| `invalid_request` (`owner_details_fields_required`) | 400 | the ending asks for more | ask for `details.fields` only, buy again with `additional` |
| `invalid_request` (`owner_details_invalid`) | 400 | an owner detail is wrong (a country that isn't a code, a phone without `+`), or the registry refused one; nothing charged | fix `details.field` (each in `details.problems`) at `details.console_url`, buy again |
| `provider_failed` | 502 | the registry refused the order for another reason; `message` says it; nothing charged | act on the reason, or write to support@vibiz.ai |
| `invalid_request` (`premium_confirmation_required`) | 400 | a premium name | confirm the price with `confirm_premium: true` |
| `forbidden` (`owner_only`) | 403 | a Limited key | send the owner `details.console_url` |
| `conflict` (`in_use`) | 409 | `use` on a name another project has | `move` it (the command is in `next_step`), or use another name under the domain |
| `conflict` (`registering` / `expired`) | 409 | `use` before the registry confirmed, or after it lapsed | wait a minute, or renew |
| `not_found` (`not_owned`) | 404 | `use` on a domain this account didn't buy | `vibiz domains owned` lists them; connect others with `vibiz domains add` |
| `conflict` (`no_confirmation_link`) | 409 | confirming before the registry's request arrived | wait, or write to support@vibiz.ai |
| `provider_failed` (`confirmation_failed`) | 502 | the registry didn't take the confirmation | try again in a few minutes, or write to support |
| `invalid_request` (`field`) | 400 | a DNS record that isn't valid (an A that isn't an IPv4 address, an MX without `priority`, a CNAME at the apex…) | `message` says why and `next_step` how; fix `details.field` |
| `conflict` (`cname_conflict`) | 409 | a CNAME sharing a name with other records | another name, or remove those first |
| `conflict` (`managed_record`) | 409 | removing a record we keep | `next_step` says what to change instead; `force` only if you mean it |
| `provider_failed` (`dns_record_not_added`) | 502 | the DNS host answered without an error but the record isn't in the zone (often a clash with a record it keeps there, like the domain's own address while it's on a project); `vibiz domains point` reports the same when the change didn't take, and nothing changed for visitors | `next_step` says what to do: try again in a minute, use `vibiz domains point` to send the name elsewhere, or point a subdomain (`app.`) instead |
| `invalid_request` (`dns_elsewhere`) | 400 | DNS records of a domain connected from elsewhere | add the record where the domain was bought |
