DNS providers dns-providers
Admin only. Stores DNS provider accounts (such as Alibaba Cloud or Cloudflare); credentials are verified online before saving and only the last 4 characters are ever returned.
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/dns-providersList DNS providers
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` |
type | string | Only list providers of this type (such as aliyun). |
/api/v2/dns-providersCreate DNS provider
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
auth_id | string | Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used). |
auth_key | string | Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted. |
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. |
gateway | string | Self-hosted API gateway address (used by dnsdun only). |
nameRequired | string | Name |
remark | string | Remark |
ttl | integer | Default TTL (seconds) of records under this account. |
typeRequired | string | Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun. |
/api/v2/dns-providers/{id}Get DNS provider
Authentication: Admin only
/api/v2/dns-providers/{id}Update DNS provider
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
auth_id | string | Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used). |
auth_key | string | Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted. |
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. |
gateway | string | Self-hosted API gateway address (used by dnsdun only). |
nameRequired | string | Name |
remark | string | Remark |
ttl | integer | Default TTL (seconds) of records under this account. |
typeRequired | string | Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun. |
/api/v2/dns-providers/{id}Delete DNS provider
Authentication: Admin only
/api/v2/dns-providers/{id}/refreshRefresh lines of all domains of an account
Authentication: Admin only
DNS providers object
| Field | Type | Description |
|---|---|---|
auth_id | string | Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used). |
auth_key | string | Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted. |
auth_key_hint | string | Last 4 characters of the credential (padded with * in front); the original is never returned. |
auth_unreadable | boolean | True when a credential is stored but cannot be decrypted (the master credential key does not match or the data was altered); auth_key_hint is then empty. False when no credential was ever configured (auth_key_hint is also empty). The panel uses it to tell "credential unreadable" from "no credential configured". |
created_at | string | Created at |
degrade_count | integer | Number of line fallback rows (line_degrades) for root domains under this account; 0 if none. The fallback strip in the DNS settings sidebar reads it. |
domain_count | integer | Number of root domains hosted under this account (including disabled and migrating ones); 0 if none. |
domains | integer | Number of domains pulled. |
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. |
failed | integer | Number of domains whose pull failed. |
gateway | string | Self-hosted API gateway address (used by dnsdun only). |
id | integer | Record ID |
line_cap | DnsLineCap | Line capability of an account (tag and tooltip in the DNS settings page). |
lines | integer | Total line count of the successful pulls. |
name | string | Name |
ok | integer | Number of domains pulled successfully. |
remark | string | Remark |
ttl | integer | Default TTL (seconds) of records under this account. |
type | string | Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun. |
updated_at | string | Updated at |
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"
}