Version 2.4.7.20261116085428 · latest

CNAME access domains cname-domains

Admin only. Root domains used to build CNAME access names, each owned by a DNS provider account; supports migrating everything to a new root domain and checking whether customers have switched their records.

Pick an endpoint to see its example call on the right.

DNS and accessAuthentication: Admin only15 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/cname-domainsList CNAME access domains

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
domainstring Only list root domains containing this text (partial match, case-insensitive; surrounding spaces and a trailing dot are ignored).
typestring Only list domains belonging to this provider type (such as aliyun).
dns_provider_idinteger Only list domains belonging to this account.
statusCnameDomainStatus Only list domains in this status.
Values ["active","retiring"]
POST/api/v2/cname-domainsCreate CNAME access domain

Authentication: Admin only

Request body application/json

FieldTypeDescription
dns_provider_idRequiredinteger ID of the provider account hosting this root domain.
domainRequiredstring Lowercase root domain, such as cdn.example.com.
expected_updated_atstring Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create.
expire_atstring Expiry date entered by the admin, YYYY-MM-DD; when empty, a daily job fetches it from the registry (see effective_expire_at).
remarkstring Remark
statusCnameDomainStatus active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain).
Values ["active","retiring"]
GET/api/v2/cname-domains/optionsList CNAME access domain options

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
statusCnameDomainStatus Only list domains in this status.
Values ["active","retiring"]
PUT/api/v2/cname-domains/statusBatch set CNAME access domain status

Authentication: Admin only

Request body application/json

FieldTypeDescription
idsRequiredinteger[] IDs of the access domains to update.
statusRequiredCnameDomainStatus active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain).
Values ["active","retiring"]
PUT/api/v2/cname-domains/{id}Update CNAME access domain

Authentication: Admin only

Request body application/json

FieldTypeDescription
dns_provider_idRequiredinteger ID of the provider account hosting this root domain.
domainRequiredstring Lowercase root domain, such as cdn.example.com.
expected_updated_atstring Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create.
expire_atstring Expiry date entered by the admin, YYYY-MM-DD; when empty, a daily job fetches it from the registry (see effective_expire_at).
remarkstring Remark
statusCnameDomainStatus active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain).
Values ["active","retiring"]
DELETE/api/v2/cname-domains/{id}Delete CNAME access domain

Authentication: Admin only

Query parameters

FieldTypeDescription
local_onlyboolean When true, delete only the local record and do not clean up provider-side records under this root domain.
POST/api/v2/cname-domains/{id}/lines/refreshReload lines of a domain

Authentication: Admin only

POST/api/v2/cname-domains/{id}/migrateMigrate CNAME access domain

Authentication: Admin only

Request body application/json

FieldTypeDescription
notifyboolean Whether to send in-app messages to the affected customers.
Default true
retireboolean Whether to set the old domain to retiring.
Default true
target_idRequiredinteger ID of the target root domain.
GET/api/v2/cname-domains/{id}/switch-checkCheck switch status after migration

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
stateCnameSwitchState Only list rows in this check state.
Values ["changed","unchanged","not_cname","failed","pending"]
qstring Fuzzy match on customer name, site domain or actual resolution.
GET/api/v2/cname-domains/{id}/switch-check/exportExport switch check table

Authentication: Admin only

Query parameters

FieldTypeDescription
stateCnameSwitchState Only list rows in this check state.
Values ["changed","unchanged","not_cname","failed","pending"]
qstring Fuzzy match on customer name, site domain or actual resolution.
POST/api/v2/cname-domains/{id}/switch-check/remindRemind customers who have not switched

Authentication: Admin only

POST/api/v2/cname-domains/{id}/switch-check/runRun switch check now

Authentication: Admin only

CNAME access domains object

FieldTypeDescription
actualstring What it actually resolves to (CNAME target or IP); on lookup failure, the reason (NXDOMAIN, Timeout, ...).
changedinteger Number of rows now switched.
check_rowsinteger Number of check rows created (one per site domain).
checkedinteger Number of rows rechecked.
checked_atstring Time of the last resolution check.
codestring Provider edition code; empty when unreadable.
created_atstring Created at
read-only
dns_provider_idinteger ID of the provider account hosting this root domain.
domainstring Lowercase root domain, such as cdn.example.com.
domainsLineOptionDomain[] All domains of the group (bound as main or backup group).
editionCnameEdition Edition and line summary of a domain at its provider (providers that expose no edition give only line_count and granularity).
effective_expire_atstring Effective expiry date, YYYY-MM-DD - the admin-entered value if set, otherwise the one fetched from the registry (RDAP/WHOIS); null if neither. The admin is reminded 30, 7 and 1 days before expiry and once after it.
errstring Reason of the last failed pull; empty after a success.
example_hostnamestring An existing access name (without the root domain), used by the wizard to build old and new access address examples.
expected_updated_atstring Optimistic lock (used on update) - the updated_at of the resource as the caller read it. If it differs from the stored one, 409 stale_version is returned and nothing is saved; omit to skip the check; ignored on create.
expire_atstring Expiry date entered by the admin, YYYY-MM-DD; when empty, a daily job fetches it from the registry (see effective_expire_at).
expire_check_errorstring Reason the latest automatic expiry lookup at the registry failed; null if the last lookup succeeded, none has run yet, or the expiry date was entered by the admin.
expire_fail_countinteger Number of consecutive failed automatic expiry lookups (reset on success; 0 when the expiry date was entered by the admin). After 7 consecutive failures with still no expiry date, the admin is notified once.
expire_sourceCnameExpireSource Source of the effective expiry date: manual - entered by the admin; auto - fetched from the registry; none - no expiry date.
Values ["manual","auto","none"]
failedinteger Number of rows whose lookup failed.
fromstring Source root domain.
granularitystring Granularity: province=carrier x province, isp=carrier only, default=default only, none=lines not loaded.
Values ["province","isp","default","none"]
idinteger Record ID
read-only
idsRequiredinteger[] IDs of the access domains to update.
last_checked_atstring Time of the most recent check among this root domain's check rows; null if not migrated or never checked.
line_countinteger Line count (all nodes of the line tree, default line included); 0 if not loaded.
line_taginteger Number of nodes whose line tag uses this root domain (their tags are cleared when the root domain is deleted).
messagedinteger Number of customers who received an in-app message.
min_ttlinteger Minimum TTL in seconds; 0 = unknown.
namestring Edition display name; empty when unreadable.
new_targetstring CNAME target after the switch.
nodesLineOptionNode[] Union of unified lines (excluding default and provider-specific lines).
not_cnameinteger Number of rows not using a CNAME.
notified_atstring Time the customer was notified.
notifyboolean Whether to send in-app messages to the affected customers.
Default true
old_targetstring CNAME target before the switch.
packageinteger Number of package access names switched.
package_liststring[] First 20 purchased packages referencing this root domain.
paidboolean Paid edition (inferred from the provider edition code; false when unreadable).
privateLinePrivateGroup[] Provider-specific lines grouped by domain; domains without any are omitted.
provider_namestring Name of the owning account.
provider_typestring Provider type of the owning account.
pulled_atstring Time of the last successful pull; null if never pulled per domain.
remarkstring Remark
retireboolean Whether to set the old domain to retiring.
Default true
siteinteger Number of site access names switched.
site_countinteger Total number of websites, layer-4 forwards and packages referencing this root domain (same basis as site+stream+package in /cname-domains/{id}/refs); 0 when nothing references it.
site_idinteger Site ID
site_liststring[] List of site access names switched.
skippedobject[] Skipped access domains with reasons.
stateCnameSwitchState changed: already switched; unchanged: not switched yet; not_cname: not a CNAME access (points elsewhere or only has an A record); failed: lookup failed; pending: waiting to be checked.
Values ["changed","unchanged","not_cname","failed","pending"]
statusCnameDomainStatus active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain).
Values ["active","retiring"]
streaminteger Number of TCP/UDP forwarding access names switched.
stream_liststring[] First 20 TCP/UDP forwardings (id:<id> <access name>).
switch_changedinteger How many of them already point their CNAME to the new root domain (check state changed); null if not migrated.
switch_pendinginteger How many of them have not been checked yet (check state pending); null if not migrated.
switch_totalinteger Total number of website domains to verify after the migration; null if not migrated (switched_to is empty).
switched_atstring Time of the migration; empty if not migrated.
switched_tointeger ID of the root domain it was migrated to.
switched_to_domainstring Name of the root domain it was migrated to; empty if not migrated.
target_idRequiredinteger ID of the target root domain.
tenant_idinteger Owner tenant (user) ID
tostring Target root domain.
unchangedinteger Number of rows still not switched.
updatedinteger Number of domains actually updated.
updated_atstring Updated at
read-only
user_liststring[] List of affected customers.
user_namestring Customer (tenant) name; empty if the tenant was deleted.
usersinteger Number of affected customers (distinct tenants owning the sites).

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command