Connect a domain
Point one of the account's own domains at this key's project over DNS, with an App-scoped key.
agent_domain_connect is a project-scoped call: unlike every other write in this section, it takes
no app_id. The project it points a domain at is whichever one the API key itself was minted
from, so this recipe needs an App key (created from a project's own API tab), not an Account
key. agent_domain_list is the companion read, the account's own domains, so you always send a
name the account actually owns.
Methods
Domains: list
List the account's registered domains (name, status, which app each is attached to). Use this BEFORE asking the user to type a domain: if they say 'connect one of my domains', call this and present the options.
Domains: connect to this VPS
Point one of the account's own domains (from agent_domain_list) at THIS project's VPS via DNS. Optional subdomain (e.g. 'app' -> app.example.com); omit to use the apex. Prefer a subdomain unless the user explicitly wants the apex. Attaching replaces any existing record on that exact hostname.
Both methods resolve uid from the key you send, same as everywhere else, but agent_domain_connect
also resolves app_id from it, and only a key minted from a project's API tab carries one. Call it
with an Account key and it answers -1, 'no app is bound to this action', before it looks at the
domain at all. See Authentication for the three key scopes.
Walkthrough
List the account's domains
No fields beyond your key. Each row is one domain the account registered through Xuda or
connected by delegating its nameservers, whichever project (if any) it currently points at, and
its own status.
2. Point one at this key's project
domain has to be one of the names the previous call returned. subdomain is optional and
unrelated to the app key's own project name, it is a label on the domain ("app" for
app.example.com); leave it out to point the domain's apex instead. Re-running this with a
different subdomain does not disturb a hostname you already attached, only that exact hostname's
record is replaced.
The response
agent_domain_list trims each stored domain doc to four fields:
connection_type is registered for a domain bought through Xuda (Xuda is the registrar and the
DNS) or connected for one registered elsewhere with its nameservers delegated to Xuda (DNS only,
registration stays where it was). Both work the same way for agent_domain_connect.
agent_domain_connect answers with the DNS record it actually wrote:
type depends on what kind of project the key is scoped to, not on anything you send: a VPS
project gets an A record to its IP (or AAAA on a farm VM with no public IPv4), everything else
gets a CNAME to the project's own access URL. Every record is Cloudflare-proxied (proxied: true),
so the visitor gets HTTPS at the edge either way. ssl_mode is only set on the VPS path, where Xuda
also probes and sets the zone's origin SSL mode (full, strict, or flexible); it comes back
null for a CNAME target, Cloudflare's own Universal SSL covers that case without a zone setting
to report.