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.
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.
/api/v2/cname-domainsList CNAME access domains
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
domain | string | Only list root domains containing this text (partial match, case-insensitive; surrounding spaces and a trailing dot are ignored). |
type | string | Only list domains belonging to this provider type (such as aliyun). |
dns_provider_id | integer | Only list domains belonging to this account. |
status | CnameDomainStatus | Only list domains in this status. |
/api/v2/cname-domainsCreate CNAME access domain
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
dns_provider_idRequired | integer | ID of the provider account hosting this root domain. |
domainRequired | string | Lowercase root domain, such as cdn.example.com. |
expected_updated_at | string | 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_at | string | Expiry date entered by the admin, YYYY-MM-DD; when empty, a daily job fetches it from the registry (see effective_expire_at). |
remark | string | Remark |
status | CnameDomainStatus | active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain). |
/api/v2/cname-domains/optionsList CNAME access domain options
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
status | CnameDomainStatus | Only list domains in this status. |
/api/v2/cname-domains/statusBatch set CNAME access domain status
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
idsRequired | integer[] | IDs of the access domains to update. |
statusRequired | CnameDomainStatus | active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain). |
/api/v2/cname-domains/{id}Get CNAME access domain
Authentication: Admin only
/api/v2/cname-domains/{id}Update CNAME access domain
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
dns_provider_idRequired | integer | ID of the provider account hosting this root domain. |
domainRequired | string | Lowercase root domain, such as cdn.example.com. |
expected_updated_at | string | 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_at | string | Expiry date entered by the admin, YYYY-MM-DD; when empty, a daily job fetches it from the registry (see effective_expire_at). |
remark | string | Remark |
status | CnameDomainStatus | active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain). |
/api/v2/cname-domains/{id}Delete CNAME access domain
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
local_only | boolean | When true, delete only the local record and do not clean up provider-side records under this root domain. |
/api/v2/cname-domains/{id}/line-optionsLine options of one domain
Authentication: Admin only
/api/v2/cname-domains/{id}/lines/refreshReload lines of a domain
Authentication: Admin only
/api/v2/cname-domains/{id}/migrateMigrate CNAME access domain
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
notify | boolean | Whether to send in-app messages to the affected customers. |
retire | boolean | Whether to set the old domain to retiring. |
target_idRequired | integer | ID of the target root domain. |
/api/v2/cname-domains/{id}/refsGet CNAME access domain references
Authentication: Admin only
/api/v2/cname-domains/{id}/switch-checkCheck switch status after migration
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
state | CnameSwitchState | Only list rows in this check state. |
q | string | Fuzzy match on customer name, site domain or actual resolution. |
/api/v2/cname-domains/{id}/switch-check/exportExport switch check table
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
state | CnameSwitchState | Only list rows in this check state. |
q | string | Fuzzy match on customer name, site domain or actual resolution. |
/api/v2/cname-domains/{id}/switch-check/remindRemind customers who have not switched
Authentication: Admin only
/api/v2/cname-domains/{id}/switch-check/runRun switch check now
Authentication: Admin only
CNAME access domains object
| Field | Type | Description |
|---|---|---|
actual | string | What it actually resolves to (CNAME target or IP); on lookup failure, the reason (NXDOMAIN, Timeout, ...). |
changed | integer | Number of rows now switched. |
check_rows | integer | Number of check rows created (one per site domain). |
checked | integer | Number of rows rechecked. |
checked_at | string | Time of the last resolution check. |
code | string | Provider edition code; empty when unreadable. |
created_at | string | Created at |
dns_provider_id | integer | ID of the provider account hosting this root domain. |
domain | string | Lowercase root domain, such as cdn.example.com. |
domains | LineOptionDomain[] | All domains of the group (bound as main or backup group). |
edition | CnameEdition | Edition and line summary of a domain at its provider (providers that expose no edition give only line_count and granularity). |
effective_expire_at | string | 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. |
err | string | Reason of the last failed pull; empty after a success. |
example_hostname | string | An existing access name (without the root domain), used by the wizard to build old and new access address examples. |
expected_updated_at | string | 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_at | string | 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_error | string | 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_count | integer | 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_source | CnameExpireSource | Source of the effective expiry date: manual - entered by the admin; auto - fetched from the registry; none - no expiry date. |
failed | integer | Number of rows whose lookup failed. |
from | string | Source root domain. |
granularity | string | Granularity: province=carrier x province, isp=carrier only, default=default only, none=lines not loaded. |
id | integer | Record ID |
idsRequired | integer[] | IDs of the access domains to update. |
last_checked_at | string | Time of the most recent check among this root domain's check rows; null if not migrated or never checked. |
line_count | integer | Line count (all nodes of the line tree, default line included); 0 if not loaded. |
line_tag | integer | Number of nodes whose line tag uses this root domain (their tags are cleared when the root domain is deleted). |
messaged | integer | Number of customers who received an in-app message. |
min_ttl | integer | Minimum TTL in seconds; 0 = unknown. |
name | string | Edition display name; empty when unreadable. |
new_target | string | CNAME target after the switch. |
nodes | LineOptionNode[] | Union of unified lines (excluding default and provider-specific lines). |
not_cname | integer | Number of rows not using a CNAME. |
notified_at | string | Time the customer was notified. |
notify | boolean | Whether to send in-app messages to the affected customers. |
old_target | string | CNAME target before the switch. |
package | integer | Number of package access names switched. |
package_list | string[] | First 20 purchased packages referencing this root domain. |
paid | boolean | Paid edition (inferred from the provider edition code; false when unreadable). |
private | LinePrivateGroup[] | Provider-specific lines grouped by domain; domains without any are omitted. |
provider_name | string | Name of the owning account. |
provider_type | string | Provider type of the owning account. |
pulled_at | string | Time of the last successful pull; null if never pulled per domain. |
remark | string | Remark |
retire | boolean | Whether to set the old domain to retiring. |
site | integer | Number of site access names switched. |
site_count | integer | 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_id | integer | Site ID |
site_list | string[] | List of site access names switched. |
skipped | object[] | Skipped access domains with reasons. |
state | CnameSwitchState | 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. |
status | CnameDomainStatus | active: in use; retiring: being retired (migrated away, no longer offered when choosing a package domain). |
stream | integer | Number of TCP/UDP forwarding access names switched. |
stream_list | string[] | First 20 TCP/UDP forwardings (id:<id> <access name>). |
switch_changed | integer | How many of them already point their CNAME to the new root domain (check state changed); null if not migrated. |
switch_pending | integer | How many of them have not been checked yet (check state pending); null if not migrated. |
switch_total | integer | Total number of website domains to verify after the migration; null if not migrated (switched_to is empty). |
switched_at | string | Time of the migration; empty if not migrated. |
switched_to | integer | ID of the root domain it was migrated to. |
switched_to_domain | string | Name of the root domain it was migrated to; empty if not migrated. |
target_idRequired | integer | ID of the target root domain. |
tenant_id | integer | Owner tenant (user) ID |
to | string | Target root domain. |
unchanged | integer | Number of rows still not switched. |
updated | integer | Number of domains actually updated. |
updated_at | string | Updated at |
user_list | string[] | List of affected customers. |
user_name | string | Customer (tenant) name; empty if the tenant was deleted. |
users | integer | 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.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"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"
}