> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goosybear.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Domains from the API

> Search for a domain, connect one you own, check its records and status, move it to another site, and get the steps to transfer one out.

Every site starts on a free Goosy address that looks like
`your-site.goosydoes.com`; `goosydoes.com` is the zone every Goosy-hosted site is published under. It belongs to that site and is always live. To serve a
site on a name of your own you connect a domain. These calls take the optional
`workspace` argument ([Which workspace](https://docs.goosybear.ai/api/pages.md#which-workspace)).

| Call | What it does | Calls to finish |
| - | - | - |
| `domain.search` | Finds names you could buy and what each costs per year. | One |
| `domain.connect` | Reserves a domain you already own and starts its certificate. | One |
| `page.domains` | Lists every address a site holds with its state. | One |
| `domain.status` | Re-checks domains and says where each use stands. | One |
| `domain.records` | Shows what DNS a domain has and what is still to add. | One |
| `domain.point_at_site` | Moves a domain you already hold onto a different site. | Two |
| `domain.transfer_out` | Gives you the steps to move a name we registered for you to another registrar. | Two |

## Search for a name

`domain.search` takes `query` (a bare name like `acme` or a full one like
`acme.com`) and an optional `tlds` list of endings without the dot, such as
`["com", "io"]`. It lists names you could buy with the **price per year**. Every
name is for one year and renews at the same kind of price. A name marked premium
costs more to renew as well. Read the price back to the person before they commit.

**Search only looks. It never buys.** Buying a domain happens in Goosy, on the
person's own screen, where they confirm the price. There is no call that buys.

## Connect a domain you own

`domain.connect` is documented with an example in
[Point a domain at it](https://docs.goosybear.ai/api/pages.md#point-a-domain-at-it). It does not make the domain
live. It answers the DNS records that you or whoever manages the domain's DNS must
add.

## Check where a domain stands

`page.domains` reads the recorded state of every address one site holds. See
[Read where a site answers](https://docs.goosybear.ai/api/pages.md#read-where-a-site-answers).

`domain.status` checks again on the spot. With no `domain_id` it reads every domain
the workspace holds, and `site_id` narrows it to one site's addresses. Each use of a
domain (the site address, an alias, email sending, tracked links) comes back with one
status:

* `action_needed`: the records are not answering yet. Relay what to add.
* `checking`: in place and still settling.
* `verified`: working.
* `failed`.

A site address also carries the state the Domains screen shows (Live, Waiting for
record, Issuing certificate or Needs attention) and a reason when something is wrong.
Call a name live only when it is `verified`. When `rechecked` is `false` the status is
the last one recorded, and when `checkable` is `false` it can't be confirmed from here
yet.

`domain.records` takes a `domain_id` (the name as you'd say it, such as
`links.acme.com`, or its id). If Goosy manages the domain's DNS it shows exactly what
is in place and marks the records we added. If it doesn't, it shows the records still
to add and what the name answers with now. `zone_held: false` is a normal answer, not
a problem. Relay the `copy_card` lines to the person; they are written for them to
follow.

## Move a domain to another site

`domain.point_at_site` takes `domain_id` and `site_id` and moves one of your domains
onto a different site. It answers in two calls, like the
[access calls](https://docs.goosybear.ai/api/pages-access.md). The free Goosy address belongs to its site and can't
be moved.

If `serving_now` comes back `false`, the address is assigned but not answering yet. When
`revision` is `null` the site has never been published, so publish it. When `revision`
is set, it is a name we bought for you that is not answering on the internet yet. Either
way, don't call it live.

## Move a name we bought to another registrar

`domain.transfer_out` takes a `domain_id` and answers in two calls. It prepares only;
**nothing is transferred by the call.** The unlock and the authorization code are done
in the other registrar's own dashboard, so relay the `guided_step` list in order. Relay
the eligibility reason word for word. "Eligible" means no hold is visible from the
registration date. It is not a guarantee the other registrar will accept the transfer.

## Where to go next

* [Pages API](https://docs.goosybear.ai/api/pages.md) for the full publish lifecycle.
* [Who can open a site](https://docs.goosybear.ai/api/pages-access.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.