Skip to main content

Developer guide

Domains

View as Markdown

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.

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 domainsetup.modeWhat you do
Bought on LinkScale (its DNS is on LinkScale)automaticNothing. It is connected during the create call; HTTPS follows within a few minutes.
Connected, DNS at your own providerdns_recordAdd 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.
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_actionMeaningKeep polling?
noneLive. Create links on it.No
waitLinkScale is connecting it, or issuing its HTTPS certificate.Yes, every poll_after_seconds (60)
add_dns_recordAdd setup.record at your DNS provider.Yes, slower (300)
fix_dns_recordThe DNS is wrong: apply problem.fixes (remove, then add) at problem.dns_provider.Yes, slower (300)
contact_supportIt will not move by itself (already served elsewhere, or waiting for more than 30 days).No
open_dashboardIts 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.
Browse API endpoints