Version 2.4.7.20261116085428 · latest

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.

DNS and accessAuthentication: Admin only6 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/dns-providersList DNS providers

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`
typestring Only list providers of this type (such as aliyun).
POST/api/v2/dns-providersCreate DNS provider

Authentication: Admin only

Request body application/json

FieldTypeDescription
auth_idstring Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used).
auth_keystring Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted.
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.
gatewaystring Self-hosted API gateway address (used by dnsdun only).
nameRequiredstring Name
remarkstring Remark
ttlinteger Default TTL (seconds) of records under this account.
typeRequiredstring Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun.
PUT/api/v2/dns-providers/{id}Update DNS provider

Authentication: Admin only

Request body application/json

FieldTypeDescription
auth_idstring Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used).
auth_keystring Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted.
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.
gatewaystring Self-hosted API gateway address (used by dnsdun only).
nameRequiredstring Name
remarkstring Remark
ttlinteger Default TTL (seconds) of records under this account.
typeRequiredstring Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun.
POST/api/v2/dns-providers/{id}/refreshRefresh lines of all domains of an account

Authentication: Admin only

DNS providers object

FieldTypeDescription
auth_idstring Credential ID (Alibaba Cloud AccessKey ID, DNSPod Token ID or Tencent Cloud SecretId, Cloudflare email; empty when a Cloudflare API Token is used).
auth_keystring Credential (AccessKey Secret / Token / SecretKey / API Key); required on create, omitted or empty on update = keep the existing value. Stored encrypted.
auth_key_hintstring Last 4 characters of the credential (padded with * in front); the original is never returned.
auth_unreadableboolean 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_atstring Created at
read-only
degrade_countinteger 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_countinteger Number of root domains hosted under this account (including disabled and migrating ones); 0 if none.
domainsinteger Number of domains pulled.
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.
failedinteger Number of domains whose pull failed.
gatewaystring Self-hosted API gateway address (used by dnsdun only).
idinteger Record ID
read-only
line_capDnsLineCap Line capability of an account (tag and tooltip in the DNS settings page).
linesinteger Total line count of the successful pulls.
namestring Name
okinteger Number of domains pulled successfully.
remarkstring Remark
ttlinteger Default TTL (seconds) of records under this account.
typestring Provider type: aliyun, cloudflare, dnspod_cn, dnspod_com, dns_la, dnsdotcom, dnsdun.
updated_atstring Updated at
read-only

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