# Domains

A link lives on a domain. Besides the shared LinkScale domains, a project
can have its own: bought on LinkScale, or connected from the dashboard.
Through the API you can add **subdomains** of those domains
(`shop.mydomain.com` under `mydomain.com`) and follow each one until it
is live - which is what an integration that puts every link on its own
subdomain needs.

## One subdomain per link

There are no wildcard hostnames: a link answers on exactly the domain it
was created on, and every subdomain is created and connected on its own.
Links on different subdomains are independent. Each subdomain uses one
domain slot of the plan, exactly like in the dashboard.

## How a subdomain connects

| Parent domain | `setup.mode` | What you do |
| --- | --- | --- |
| Bought on LinkScale (its DNS is on LinkScale) | `automatic` | Nothing. It is connected during the create call; HTTPS follows within a few minutes. |
| Connected, DNS at your own provider | `dns_record` | Add the one CNAME in `setup.record` (`shop` -> `in.saascustomdomains.com`). It connects by itself once the record is seen. |

With a DNS provider of your own, one **wildcard** record
(`*.mydomain.com` CNAME `in.saascustomdomains.com`) covers every
subdomain you will ever create: each new one then connects with no DNS
change at all.

## Recipe

1. Create the subdomain - `POST /api/v1/domains` with
   `{ "domain": "abc.mydomain.com" }`. Retrying is safe: an existing one
   is answered with `created: false`.
2. Follow it - `GET /api/v1/domains/abc.mydomain.com` (the `status_url`
   of the answer), waiting `poll_after_seconds` between calls, until
   `domain.usable` is true.
3. Create the link - `PUT /api/v1/links` with
   `"domain": "abc.mydomain.com"` and `"u": ""` to answer on the bare
   subdomain, or any slug.

```bash
curl -X POST https://dashboard.linkscale.to/api/v1/domains \
  -H "Authorization: Bearer $LINKSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"abc.mydomain.com"}'

curl https://dashboard.linkscale.to/api/v1/domains/abc.mydomain.com \
  -H "Authorization: Bearer $LINKSCALE_API_KEY"
```

## What to do next: `next_action`

Every answer about a domain carries exactly one `next_action`. Switch on
it; show `message` to a person.

| `next_action` | Meaning | Keep polling? |
| --- | --- | --- |
| `none` | Live. Create links on it. | No |
| `wait` | LinkScale is connecting it, or issuing its HTTPS certificate. | Yes, every `poll_after_seconds` (60) |
| `add_dns_record` | Add `setup.record` at your DNS provider. | Yes, slower (300) |
| `fix_dns_record` | The DNS is wrong: apply `problem.fixes` (remove, then add) at `problem.dns_provider`. | Yes, slower (300) |
| `contact_support` | It will not move by itself (already served elsewhere, or waiting for more than 30 days). | No |
| `open_dashboard` | Its status (unpaid, disabled...) is managed from the dashboard. | No |

`steps` shows the same thing as a progress bar - created, dns_record (only
when a record is needed), connected, https - each `done`, `in_progress`,
`action_required`, `blocked` or `pending`, with the time it completed.

## Freshness

LinkScale checks every waiting domain by itself, every few minutes, for
30 days after it was added. A status read reports the last check
(`checks.last_checked_at`) and never starts a new one, so it costs nothing
to poll and cannot change anything. `poll_after_seconds` is also sent as
the `Retry-After` header, and is null when nothing will change by itself.

## Limits

- Only subdomains of a domain already in the project. A root domain is
  bought or connected from the dashboard.
- A subdomain held by another project is refused (409).
- Creating requires `links.create`; reading requires `links.read`. The
  key owner's dashboard rights and the plan's domain quota apply.
- The MCP tools `create_subdomain` and `get_domain_status` (and the
  dashboard assistant) run exactly this code.
