Developer guide
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
- Create the subdomain -
POST /api/v1/domainswith{ "domain": "abc.mydomain.com" }. Retrying is safe: an existing one is answered withcreated: false. - Follow it -
GET /api/v1/domains/abc.mydomain.com(thestatus_urlof the answer), waitingpoll_after_secondsbetween calls, untildomain.usableis true. - Create the link -
PUT /api/v1/linkswith"domain": "abc.mydomain.com"and"u": ""to answer on the bare subdomain, or any slug.
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 requireslinks.read. The key owner's dashboard rights and the plan's domain quota apply. - The MCP tools
create_subdomainandget_domain_status(and the dashboard assistant) run exactly this code.