Skip to content
Verified

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

POST/cpi/agent_domain_list
user

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.

POST/cpi/agent_domain_connect
user

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.

This needs an App key, not an Account key

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.

curl -s https://xuda.ai/cpi/agent_domain_list \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY"}'
const res = await fetch('https://xuda.ai/cpi/agent_domain_list', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ api_key: 'YOUR_API_KEY' }),
});
const { code, data } = await res.json();
if (code > 0) for (const d of data.domains) console.log(d.domain, d.status, d.attached_app_id);
import requests

res = requests.post(
    'https://xuda.ai/cpi/agent_domain_list',
    json={'api_key': 'YOUR_API_KEY'},
)
body = res.json()
if body['code'] > 0:
    for d in body['data']['domains']:
        print(d['domain'], d['status'], d['attached_app_id'])

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.

curl -s https://xuda.ai/cpi/agent_domain_connect \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_APP_API_KEY","domain":"example.com","subdomain":"app"}'
const res = await fetch('https://xuda.ai/cpi/agent_domain_connect', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_APP_API_KEY',
    domain: 'example.com',
    subdomain: 'app',
  }),
});
const { code, data } = await res.json();
if (code > 0) console.log(data.record.type, data.record.name, data.record.target);
import requests

res = requests.post(
    'https://xuda.ai/cpi/agent_domain_connect',
    json={'api_key': 'YOUR_APP_API_KEY', 'domain': 'example.com', 'subdomain': 'app'},
)
body = res.json()
if body['code'] > 0:
    print(body['data']['record']['type'], body['data']['record']['name'], body['data']['record']['target'])

The response

agent_domain_list trims each stored domain doc to four fields:

json
{
  "code": 1,
  "data": {
    "count": 2,
    "domains": [
      {
        "domain": "example.com",
        "status": "active",
        "connection_type": "registered",
        "attached_app_id": null
      },
      {
        "domain": "example.org",
        "status": "active",
        "connection_type": "connected",
        "attached_app_id": "app_5d9e21"
      }
    ]
  }
}

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:

json
{
  "code": 1,
  "data": {
    "ok": true,
    "record": {
      "type": "A",
      "name": "app.example.com",
      "target": "203.0.113.42",
      "proxied": true,
      "ssl_mode": "full"
    }
  }
}

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.

Errors

Next