Custom hostnames API

When an app's end-customer brings their own domain — a status page on status.client1.com, a storefront on shop.client2.ie — someone still has to create a DNS record. This API is the machine seam that closes that gap: the app registers the hostname, and SpipCP either creates the record itself (when it controls the zone) or hands back the exact records to show the customer.

Auth — a site-bound token

Every call needs a site-bound spat_… token: minted on the site's Networking → Custom hostnames card, scoped to custom-hostnames permissions only, bound to exactly one site. It can never reach another site or any fleet-wide surface — a leaked token's blast radius is one site's DNS automation, nothing else.

Authorization: Bearer spat_xxxxxxxx

📷Site → Networking → Custom hostnames — mint a site-bound token, the automated-zones allow-list, and the registered-hostnames table.img/sites-on-demand-api.avif

The five calls

Reachable as typed oRPC (client.customHostnames.*) and as REST on /api/v1 — see the transport note for how both doors share one procedure. Every mutation is audited; probe writes nothing, so it is not.

probe

{ siteId, hostname } → { hostname, verdict, reason, tier, zoneName, records, cnameTarget, registered }

The first call an app makes, and the only read-only one: what would register do for this hostname? It runs the same planner, collision guard and allow-list check register runs, and writes nothing at all — no row, no job, no audit entry. The point is the customer-facing branch: the moment someone types status.client1.com, the app can say "DNS is handled automatically" or render the exact records to add — before asking them to prove they own it.

curl -X POST https://panel.example.com/api/v1/customHostnames/probe \
  -H "Authorization: Bearer spat_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "siteId": "<site-uuid>", "hostname": "status.client1.com" }'

{
  "hostname": "status.client1.com",
  "verdict": "auto",
  "reason": null,
  "tier": "hosted",
  "zoneName": "client1.com",
  "records": [
    { "type": "CNAME", "name": "status.client1.com", "value": "app.example.com", "ttl": 300 }
  ],
  "cnameTarget": "app.example.com",
  "registered": false
}

records is always the planned set — identical to what register would write or hand out — so an app renders it once, whatever the verdict. registered is true when this site already holds a row for the hostname; the probe still returns the live plan, and status is where its state lives.

Everything answers in band: a collision comes back as verdict: "blocked", not a 409. A probe is a question, and every answer to it is a normal response.

register

{ siteId, hostname } → { id, hostname, tier, state, records, reason? }

curl -X POST https://panel.example.com/api/v1/customHostnames/register \
  -H "Authorization: Bearer spat_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "siteId": "<site-uuid>", "hostname": "status.client1.com" }'

state is one of:

reason (only on instructions):

Hostname validation: lowercase FQDN, ≤253 chars, no wildcard, not a bare IP. 409 if the hostname collides — already attached to a site as an ordinary domain, or already registered to a different site. 429 if the call is over the rate limit (below). Re-registering the exact same (siteId, hostname) is safe and returns the current row.

status

{ siteId, hostname } → { state, tier, records, dns: { resolves, checkedAt }, cert: { issued, notAfter?, observedAt? }, failureRemedy? }

dns.resolves is a cached, short-timeout lookup asserting the hostname resolves to the planned target — advisory, never blocking (a slow resolver just means a stale false a little longer, never a hang). cert joins the node's observed certificate facts; issuance is lazy (see the polling recipe below), so cert.issued only flips to true after the app primes the first handshake. failureRemedy is set only when state is failed or removal-manual.

list

{ siteId } → { hostnames: Row[] } — every hostname registered for the site, newest-first.

remove

{ siteId, hostname } → { state: "removed" | "removing" }

Deletes only the records SpipCP itself created — never a guess at what might belong to somebody else. A hostname that never had a record written (an external/instructions row) is deleted immediately → removed. A Hosted/Connected hostname returns removing and the actual record deletion runs as a background job; poll status for the terminal outcome — the row disappears (removed) or lands on removal-manual when the DNS provider has no automated-delete capability yet, in which case its failureRemedy carries the records to remove by hand. Certificate removal is never attempted — disabling a hostname is not revoking its cert; already-issued certs expire naturally and harmlessly.

The recommended flow

Hard requirements + failure honesty

• 409 — a collision (already attached, or registered to a different site). Not retryable without changing the hostname.

• 429 — over the per-token rate limit. The response carries a Retry-After hint. The two windows are separate, so a keystroke-adjacent probe can never eat a registration's budget:

  Call	Limit per token
  probe	600 / hour
  register	120 / hour

• failed + failureRemedy — a Hosted/Connected write was attempted and genuinely failed (a box unreachable, a bad credential). The remedy is the actual error, not a generic message — surface it or retry later; the row never gets silently stuck.

• removal-manual — see remove above. Never a silent orphan: the row survives with the records to clean up by hand in its failureRemedy, observable via status. This also covers a Hosted removal where a nameserver box rejected the delete — the row won't vanish while the record still resolves.

• Rotate the token on suspicion. Mint a new one, swap it into the app's environment, then revoke the old one from the site card.