Docs
DocsAPI

API

The SDM Public API reference documents the customer-callable DNS and Cloudflare operations served by the panel's HTTPS API listener on port 882.

Where to find it: Documentation > DNS Manager > API.

Available to: External API users created in SDM. The root account is deliberately rejected; each API user remains limited by active state, permission, source-IP policy, and zone ownership.

What this page does

Use this page to build integrations without guessing route paths or request keys. It covers 30 public operations: 18 actions on the DNS compatibility endpoint and 12 clean domain/Cloudflare routes. Private service, peer, panel-session, and local administration interfaces are deliberately outside this customer contract.

Before you start

  1. Create a dedicated non-root API user and keep both its panel account and API account active.
  2. Choose either X-API-Name/X-API-Key headers or HTTP Basic authentication.
  3. If API source rules are configured, send requests from an allowed IP or CIDR.
  4. Use the exact origin https://panel.example.com:882. The port is part of the address, not decorative punctuation.
  5. Read the target before a mutation and keep credentials out of browser JavaScript, source control, logs, and screenshots.

Authentication and request formats

The compatibility endpoint reads URL query keys for GET calls and URL-encoded form fields for POST calls; it does not treat a JSON body as compatibility form input. The clean Cloudflare routes use path/query parameters and JSON bodies exactly as listed in each card. All responses are JSON.

curl -sS 'https://panel.example.com:882/api/v1/dns?action=ping' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Optional source metadata headers

The DNS compatibility endpoint records these headers after a successful call. They improve the root-only DNS API Sources view and do not replace authentication. When several aliases are present, SDM uses the first non-empty value in the order shown.

MeaningAccepted headers, in precedence orderFallback
Server nameX-SHM-Source-Hostname, X-SHM-Hostname, X-Server-Name, X-Hosting-Server, X-Node-NameEmpty
Public IPX-SHM-Source-IP, X-SHM-Server-IP, X-Server-IP, X-Public-IPObserved request address
Product typeX-Source-Type, X-SHM-Source-Type, X-Product-Code, X-Product-Type, X-Server-Typeapi; SHM aliases normalize to shm
Product versionX-SHM-Version, X-Product-Version, X-Server-VersionEmpty
CapabilitiesX-SHM-Capabilities, X-Server-Capabilities, X-CapabilitiesEmpty; comma, whitespace, semicolon, and pipe separators are normalized

Public operation index (30)

MethodPublic operationPurposeParameters
GET/api/v1/dns?action=pingCheck credentials and API availability1
GET/api/v1/dns?action=heartbeatRecord an integration heartbeat1
GET/api/v1/dns?action=nodes_listList public node status2
GET/api/v1/dns?action=zones_listList zones owned by the API user5
GET/api/v1/dns?action=zone_getRead one complete zone2
POST/api/v1/dns?action=zone_createCreate an owned DNS zone4
POST/api/v1/dns?action=zone_replaceReplace a complete zone safely8
POST/api/v1/dns?action=zone_deleteDelete an owned zone4
GET/api/v1/dns?action=zone_checkValidate a zone2
POST/api/v1/dns?action=zone_rectifyRectify zone metadata2
GET/api/v1/dns?action=zone_dnssec_statusRead DNSSEC state and DS material2
POST/api/v1/dns?action=zone_dnssec_enableEnable DNSSEC signing2
POST/api/v1/dns?action=zone_dnssec_disableDisable DNSSEC safely4
POST/api/v1/dns?action=zone_dnssec_rolloverAdvance a staged DNSSEC rollover4
GET/api/v1/dns?action=records_listList records in one zone4
POST/api/v1/dns?action=record_addAdd a DNS record10
POST/api/v1/dns?action=record_updateUpdate a DNS record value9
POST/api/v1/dns?action=record_deleteDelete a record value or RRset5
GET/api/external/cloudflare/domainsList Cloudflare-managed domains3
GET/api/external/cloudflare/domains/{domain}/statusRead domain provider status1
POST/api/external/cloudflare/domains/{domain}/syncSynchronize a domain to its desired provider1
POST/api/external/cloudflare/domains/{domain}/enableEnable Cloudflare for a domain4
POST/api/external/cloudflare/domains/{domain}/disableDisable Cloudflare and return to local DNS6
GET/api/external/cloudflare/domains/{domain}/settingsRead supported Cloudflare settings1
PATCH/api/external/cloudflare/domains/{domain}/settings/{setting}Update one Cloudflare setting3
POST/api/external/cloudflare/domains/{domain}/cache/purgePurge Cloudflare cache6
GET/api/external/cloudflare/domains/{domain}/recordsList DNS records for a Cloudflare-capable domain3
POST/api/external/cloudflare/domains/{domain}/recordsCreate and synchronize a DNS record9
PATCH/api/external/cloudflare/domains/{domain}/records/{record_id}Update and synchronize one DNS record10
DELETE/api/external/cloudflare/domains/{domain}/records/{record_id}Delete and synchronize one DNS record2

Endpoint reference

GET/api/v1/dns?action=pingpublic APICheck credentials and API availability

What this operation does

Authenticates the caller and confirms that the public DNS API is responding.

Endpoint

GET /api/v1/dns?action=ping; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires an active external API identity with dns.ping permission. Root is not accepted by the external API.

Parameters (1)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
ping
Default
No default
Example
ping

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value ping. Action names are case-sensitive.

Complete request template

This template names all 1 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "ping"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=ping' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

A successful response contains success=true and the authenticated identity's liveness information.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Use ping before a longer workflow. It proves authentication and reachability, not access to every zone or mutation.

GET/api/v1/dns?action=heartbeatpublic APIRecord an integration heartbeat

What this operation does

Authenticates the sender and records its latest activity and optional source metadata for the DNS API Sources page.

Endpoint

GET /api/v1/dns?action=heartbeat; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires a valid active external API identity. The same source-IP policy used by other public calls applies.

Parameters (1)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
heartbeat
Default
No default
Example
heartbeat

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value heartbeat. Action names are case-sensitive.

Complete request template

This template names all 1 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "heartbeat"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=heartbeat' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-SHM-Source-Hostname: hosting-01.example.net' \
  -H 'X-Source-Type: shm'

Successful result

The response reports heartbeat_recorded and returns the normalized sender metadata that SDM stored.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

A heartbeat is an activity signal, not a DNS write and not a cluster health probe. Send it at a sensible interval; one per second only teaches the audit log to dislike you.

GET/api/v1/dns?action=nodes_listpublic APIList public node status

What this operation does

Returns the node inventory visible through the external DNS integration contract.

Endpoint

GET /api/v1/dns?action=nodes_list; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.nodes.read permission.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
nodes_list
Default
No default
Example
nodes_list

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value nodes_list. Action names are case-sensitive.

statusOptional
Send in
Query string or form body
Type
enum
Accepted values
empty/default, active, pending, removed, or all
Default
Empty: active and pending
Example
active

Filters nodes by registration state.

Validation and use: Use all only when you also need removed nodes; an empty value returns active and pending nodes.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "nodes_list",
    "status": "active"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=nodes_list&status=active' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains count and a nodes array for the selected status set.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

This is a customer-callable summary action. It does not expose or invoke the private peer-to-peer cluster interface.

GET/api/v1/dns?action=zones_listpublic APIList zones owned by the API user

What this operation does

Returns the caller's accessible zones with search and offset pagination.

Endpoint

GET /api/v1/dns?action=zones_list; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.read permission; ownership filtering remains active.

Parameters (5)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zones_list
Default
No default
Example
zones_list

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zones_list. Action names are case-sensitive.

searchOptional
Send in
Query string or form body
Type
string
Accepted values
A zone-name search fragment
Default
Empty
Example
example

Filters the zone list by name.

Validation and use: If both search and q are supplied, search takes precedence.

qOptional
Send in
Query string or form body
Type
string
Accepted values
A zone-name search fragment
Default
Empty
Example
example

Compatibility alias for search.

Validation and use: Use either q or search. If both are present, search wins.

limitOptional
Send in
Query string or form body
Type
integer
Accepted values
A positive page size accepted by the service
Default
1000
Example
100

Maximum number of zones requested for this page.

Validation and use: Use a bounded page size and follow next_offset when returned.

offsetOptional
Send in
Query string or form body
Type
integer
Accepted values
0 or greater
Default
0
Example
0

Number of matching zones to skip.

Validation and use: Start at 0 and advance by the returned page size or next_offset.

Complete request template

This template names all 5 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zones_list",
    "search": "example",
    "q": "example",
    "limit": 100,
    "offset": 0
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=zones_list&search=example&limit=100&offset=0' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains total, filtered, limit, offset, next_offset, and the zones array.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Pagination is safer than assuming every installation has a small zone list. Search operates inside the caller's ownership boundary.

GET/api/v1/dns?action=zone_getpublic APIRead one complete zone

What this operation does

Fetches one owned zone and its current authoritative data.

Endpoint

GET /api/v1/dns?action=zone_get; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.read permission and access to the requested zone.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_get
Default
No default
Example
zone_get

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_get. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_get",
    "name": "example.com"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=zone_get&name=example.com' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains the current zone object, including records and authoritative state supplied by SDM.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Read the zone immediately before replacement or destructive work so your integration is not acting on stale content.

POST/api/v1/dns?action=zone_createpublic APICreate an owned DNS zone

What this operation does

Creates a Native zone for the authenticated API user and applies the supplied or local fallback nameservers.

Endpoint

POST /api/v1/dns?action=zone_create

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission. The new zone is assigned to the authenticated API user.

Parameters (4)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_create
Default
No default
Example
zone_create

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_create. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

kindOptional
Send in
Query string or form body
Type
string
Accepted values
Native is the supported normal value
Default
Native
Example
Native

PowerDNS zone kind.

Validation and use: Leave this as Native unless Synconix support has confirmed a different deployment contract.

nameserversOptional
Send in
Query string or form body
Type
string
Accepted values
Comma-, whitespace-, or newline-separated nameserver hostnames
Default
The server hostname when usable; otherwise the local fallback
Example
ns1.example.net, ns2.example.net

Nameservers used when SDM creates the zone.

Validation and use: Use fully qualified names. An empty value invokes the server-side fallback.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_create",
    "name": "example.com",
    "kind": "Native",
    "nameservers": "ns1.example.net, ns2.example.net"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_create' \
  --data-urlencode 'name=example.com' \
  --data-urlencode 'kind=Native' \
  --data-urlencode 'nameservers=ns1.example.net, ns2.example.net'

Successful result

The response identifies the created zone and its initial authoritative state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Creating a zone in SDM does not change registrar delegation. Point the domain at the intended nameservers separately and verify from a public resolver.

POST/api/v1/dns?action=zone_replacepublic APIReplace a complete zone safely

What this operation does

Loads a complete zone file, reconciles ownership and optional DNSSEC policy, rectifies when requested, and registers the change for normal SDM synchronization.

Endpoint

POST /api/v1/dns?action=zone_replace

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires a trusted active API identity that may access the zone. Non-root identities can assign only themselves as owner; the external API does not accept the root account.

Parameters (8)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_replace
Default
No default
Example
zone_replace

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_replace. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

zonefileConditional
Send in
Query string or form body
Type
string
Accepted values
RFC-style zone text using only $ORIGIN and $TTL directives
Default
No default
Example
$ORIGIN example.com. $TTL 3600 @ IN A 192.0.2.10

Primary key for the complete zone file.

Validation and use: Required unless zone_text is used. Maximum size is 16 MiB. Do not send private signing material in the zone text.

zone_textConditional
Send in
Query string or form body
Type
string
Accepted values
Same format and limit as zonefile
Default
No default
Example
$ORIGIN example.com. $TTL 3600 @ IN A 192.0.2.10

Compatibility alias for zonefile.

Validation and use: Use one of zonefile or zone_text. If zonefile is present, it takes precedence.

dnssecOptional
Send in
Query string or form body
Type
enum
Accepted values
preserve, enabled, or disabled
Default
preserve
Example
preserve

Controls whether the existing DNSSEC policy is retained, enabled, or disabled during import.

Validation and use: Use disabled only after the parent DS has been removed. Enabled may be paired with dnssec_keyset for trusted synchronization.

dnssec_keysetConditional
Send in
Query string or form body
Type
sensitive JSON string
Accepted values
A validated SDM DNSSEC keyset for the same zone
Default
Omitted
Example
SECURE_KEYSET_FROM_TRUSTED_SYNC

Transfers an existing signing identity during authenticated SDM synchronization.

Validation and use: Valid only when dnssec=enabled. Treat it as secret material: never log it, paste it into tickets, or reuse the placeholder shown here.

rectifyOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
true when dnssec=preserve
Example
false

Runs zone rectification after a preserve-policy import.

Validation and use: When DNSSEC policy changes, SDM rectifies as part of that policy flow. Set false only when a controlled follow-up rectification is planned.

owner_usernameOptional
Send in
Query string or form body
Type
string
Accepted values
The authenticated username; root-only assignment to another account is reserved
Default
Authenticated API username
Example
dns-automation

Owner recorded for the imported zone.

Validation and use: External API users can assign only themselves because root is not a permitted external identity.

Complete request template

This template names all 8 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_replace",
    "name": "example.com",
    "zonefile": "$ORIGIN example.com.\n$TTL 3600\n@ IN A 192.0.2.10",
    "zone_text": "$ORIGIN example.com.\n$TTL 3600\n@ IN A 192.0.2.10",
    "dnssec": "preserve",
    "dnssec_keyset": "SECURE_KEYSET_FROM_TRUSTED_SYNC",
    "rectify": false,
    "owner_username": "dns-automation"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_replace' \
  --data-urlencode 'name=example.com' \
  --data-urlencode 'dnssec=preserve' \
  --data-urlencode 'rectify=true' \
  --data-urlencode 'zonefile@./example.com.zone'

Successful result

The response reports whether the zone was created or replaced, owner state, rectification, DNSSEC state, deduplication, audit recording, and synchronization delivery state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

This is a whole-zone mutation. Keep a source copy, validate it with zone_check, and do not retry blindly while another mutation reports zone_mutation_busy or delivery pending.

POST/api/v1/dns?action=zone_deletepublic APIDelete an owned zone

What this operation does

Removes one zone. If the zone is linked to Cloudflare, the caller may also request verified deletion of the Cloudflare zone.

Endpoint

POST /api/v1/dns?action=zone_delete

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission and ownership of the zone.

Parameters (4)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_delete
Default
No default
Example
zone_delete

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_delete. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

delete_cloudflare_zoneOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
false
Example
false

Requests deletion of the linked Cloudflare zone before the local zone is removed.

Validation and use: When a linked Cloudflare zone exists, set true only with the exact confirmation value.

cloudflare_delete_confirmConditional
Send in
Query string or form body
Type
string
Accepted values
The exact normalized zone name
Default
Omitted
Example
example.com

Confirms the Cloudflare deletion branch.

Validation and use: Required when delete_cloudflare_zone=true and a linked Cloudflare zone exists. It must match name exactly.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_delete",
    "name": "example.com",
    "delete_cloudflare_zone": false,
    "cloudflare_delete_confirm": "example.com"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_delete' \
  --data-urlencode 'name=example.com' \
  --data-urlencode 'delete_cloudflare_zone=false'

Successful result

The response confirms local deletion and, when requested, the verified Cloudflare deletion result.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Deletion is not a substitute for a provider migration. Export or back up the zone first and make the Cloudflare branch explicit.

GET/api/v1/dns?action=zone_checkpublic APIValidate a zone

What this operation does

Runs the authoritative zone consistency check without changing records.

Endpoint

GET /api/v1/dns?action=zone_check; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.read permission and access to the zone.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_check
Default
No default
Example
zone_check

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_check. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_check",
    "name": "example.com"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=zone_check&name=example.com' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response includes the check result and diagnostic output supplied by the authoritative DNS tooling.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Run this after an import and before assuming a syntactically accepted zone is operationally sound.

POST/api/v1/dns?action=zone_rectifypublic APIRectify zone metadata

What this operation does

Reconciles PowerDNS metadata for one owned zone after changes that require rectification.

Endpoint

POST /api/v1/dns?action=zone_rectify

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission and access to the zone.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_rectify
Default
No default
Example
zone_rectify

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_rectify. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_rectify",
    "name": "example.com"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_rectify' \
  --data-urlencode 'name=example.com'

Successful result

The response reports whether rectification completed and includes relevant command output.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Rectify is a repair operation, not a content editor. Verify the zone and DNSSEC status afterward.

GET/api/v1/dns?action=zone_dnssec_statuspublic APIRead DNSSEC state and DS material

What this operation does

Returns the current signing state, public keys, DS records for the parent, authoritative readiness, and rollover state.

Endpoint

GET /api/v1/dns?action=zone_dnssec_status; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.read permission and access to the zone.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_dnssec_status
Default
No default
Example
zone_dnssec_status

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_dnssec_status. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_dnssec_status",
    "name": "example.com"
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=zone_dnssec_status&name=example.com' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains enabled/configured state, public DS/DNSKEY material, parent observations, and any active rollover phase.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Publish only DS records returned for the current keyset. A green local state is not enough until the parent and public resolvers agree.

POST/api/v1/dns?action=zone_dnssec_enablepublic APIEnable DNSSEC signing

What this operation does

Enables signing, rectifies the zone, clears relevant cache, and registers the updated zone for normal synchronization.

Endpoint

POST /api/v1/dns?action=zone_dnssec_enable

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission and access to the zone.

Parameters (2)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_dnssec_enable
Default
No default
Example
zone_dnssec_enable

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_dnssec_enable. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_dnssec_enable",
    "name": "example.com"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_dnssec_enable' \
  --data-urlencode 'name=example.com'

Successful result

The response returns the newly active DNSSEC state and DS material, plus replication state when known.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Enabling signing is only the first half. Add the returned DS at the parent and verify authoritative readiness before calling the chain complete.

POST/api/v1/dns?action=zone_dnssec_disablepublic APIDisable DNSSEC safely

What this operation does

Disables signing only after an exact-name confirmation and the normal parent-DS safety check.

Endpoint

POST /api/v1/dns?action=zone_dnssec_disable

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission and access to the zone.

Parameters (4)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_dnssec_disable
Default
No default
Example
zone_dnssec_disable

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_dnssec_disable. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

confirmRequired
Send in
Query string or form body
Type
string
Accepted values
The exact zone name
Default
No default
Example
example.com

Confirms that the caller intends to disable DNSSEC for this zone.

Validation and use: The normalized value must exactly match name.

forceOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
false
Example
false

Bypasses selected DNSSEC safety gates in a root recovery context.

Validation and use: The public external API rejects root identities, so customer integrations must leave force=false. This key remains documented because the wrapper accepts it, but it is reserved for controlled recovery tooling.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_dnssec_disable",
    "name": "example.com",
    "confirm": "example.com",
    "force": false
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_dnssec_disable' \
  --data-urlencode 'name=example.com' \
  --data-urlencode 'confirm=example.com' \
  --data-urlencode 'force=false'

Successful result

The response returns the disabled state and the latest synchronization status.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Remove DS records at the registrar or parent first, wait for them to disappear publicly, and only then disable signing. Reversing that order can make the domain vanish for validating resolvers.

POST/api/v1/dns?action=zone_dnssec_rolloverpublic APIAdvance a staged DNSSEC rollover

What this operation does

Moves one zone through the begin, activate, and complete key-rollover phases.

Endpoint

POST /api/v1/dns?action=zone_dnssec_rollover

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.zones.write permission and access to an already signed zone.

Parameters (4)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
zone_dnssec_rollover
Default
No default
Example
zone_dnssec_rollover

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value zone_dnssec_rollover. Action names are case-sensitive.

nameRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone name affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

phaseRequired
Send in
Query string or form body
Type
enum
Accepted values
begin, activate, or complete
Default
No default
Example
begin

The exact rollover phase to execute.

Validation and use: Run phases in order. Read status between phases and update/verify the parent DS when the returned state requires it.

forceOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
false
Example
false

Bypasses selected rollover safety gates in a root recovery context.

Validation and use: External customer identities cannot use root context. Leave false unless Synconix support is operating an isolated recovery workflow.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "zone_dnssec_rollover",
    "name": "example.com",
    "phase": "begin",
    "force": false
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=zone_dnssec_rollover' \
  --data-urlencode 'name=example.com' \
  --data-urlencode 'phase=begin' \
  --data-urlencode 'force=false'

Successful result

The response reports the current keyset, rollover phase, DS material, authoritative readiness, and replication state when known.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

A rollover is a staged protocol, not three buttons to click quickly. Observe DNS and parent state between phases.

GET/api/v1/dns?action=records_listpublic APIList records in one zone

What this operation does

Returns the records visible to the authenticated owner, with optional offset pagination.

Endpoint

GET /api/v1/dns?action=records_list; accepted methods: GET or POST

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.records.read permission and access to the zone.

Parameters (4)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
records_list
Default
No default
Example
records_list

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value records_list. Action names are case-sensitive.

zoneRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

limitOptional
Send in
Query string or form body
Type
integer
Accepted values
A positive page size accepted by the service
Default
5000
Example
500

Maximum number of records requested.

Validation and use: If neither limit nor offset is supplied, the wrapper returns the full compatibility list returned by the current service.

offsetOptional
Send in
Query string or form body
Type
integer
Accepted values
0 or greater
Default
0
Example
0

Number of records to skip.

Validation and use: Use with limit for deterministic paging.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "records_list",
    "zone": "example.com",
    "limit": 500,
    "offset": 0
  }
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/v1/dns?action=records_list&zone=example.com&limit=500&offset=0' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains zone, records, limit, offset, and next_offset when another page exists.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Obtain the current record content from this action before update or value-specific deletion.

POST/api/v1/dns?action=record_addpublic APIAdd a DNS record

What this operation does

Adds a value to an RRset, normalizes names and record-specific content, and synchronizes eligible Cloudflare state.

Endpoint

POST /api/v1/dns?action=record_add

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.records.write permission and access to the zone.

Parameters (10)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
record_add
Default
No default
Example
record_add

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value record_add. Action names are case-sensitive.

zoneRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

nameOptional
Send in
Query string or form body
Type
string
Accepted values
@, a relative label, or a name inside the zone
Default
@
Example
www

Record owner name.

Validation and use: SDM normalizes the name into the selected zone.

typeRequired
Send in
Query string or form body
Type
DNS RR type
Accepted values
A valid PowerDNS record type. The SDM editor currently offers A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, CAA, AFSDB, DNAME, DS, and HINFO
Default
No default
Example
A

Record type.

Validation and use: Use uppercase conventional names. Proxied is valid only for A, AAAA, and CNAME.

contentConditional
Send in
Query string or form body
Type
string
Accepted values
Record data valid for the selected type
Default
No default
Example
192.0.2.10

Record value.

Validation and use: Required except that an MX value can be constructed from mx_priority and mx_destination.

mx_priorityOptional
Send in
Query string or form body
Type
integer
Accepted values
Valid MX priority
Default
10 when MX content is constructed
Example
10

Priority used when building MX content.

Validation and use: Used only for MX when mx_destination is provided and content is empty.

mx_destinationConditional
Send in
Query string or form body
Type
hostname
Accepted values
A valid mail-exchanger hostname
Default
Omitted
Example
mail.example.com

Destination used to build MX content.

Validation and use: For MX, provide this with mx_priority when content is omitted.

ttlOptional
Send in
Query string or form body
Type
integer
Accepted values
A positive TTL in seconds
Default
3600
Example
3600

Record TTL.

Validation and use: Use a value appropriate to the change frequency and migration plan.

disabledOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
false
Example
false

Creates the record in a disabled state when true.

Validation and use: Use an explicit true/false value. Omitting an optional boolean keeps its documented default.

proxiedOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
Provider/default state when omitted
Example
false

Requests Cloudflare proxying for an eligible record.

Validation and use: Only meaningful for A, AAAA, and CNAME on a Cloudflare-capable zone. Other types must stay DNS-only.

Complete request template

This template names all 10 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "record_add",
    "zone": "example.com",
    "name": "www",
    "type": "A",
    "content": "192.0.2.10",
    "mx_priority": 10,
    "mx_destination": "mail.example.com",
    "ttl": 3600,
    "disabled": false,
    "proxied": false
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=record_add' \
  --data-urlencode 'zone=example.com' \
  --data-urlencode 'name=www' \
  --data-urlencode 'type=A' \
  --data-urlencode 'content=192.0.2.10' \
  --data-urlencode 'ttl=3600' \
  --data-urlencode 'disabled=false' \
  --data-urlencode 'proxied=false'

Successful result

The response identifies the created or reconciled record and reports the resulting synchronization state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Adding an existing value may update its disabled/proxy state rather than create a duplicate. Read the RRset afterward.

POST/api/v1/dns?action=record_updatepublic APIUpdate a DNS record value

What this operation does

Replaces one existing record value and preserves or changes its TTL, disabled state, and eligible proxy preference.

Endpoint

POST /api/v1/dns?action=record_update

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.records.write permission and access to the zone.

Parameters (9)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
record_update
Default
No default
Example
record_update

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value record_update. Action names are case-sensitive.

zoneRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

nameOptional
Send in
Query string or form body
Type
string
Accepted values
@, relative label, or name inside the zone
Default
Empty; resolved by the underlying record contract
Example
www

Record owner name.

Validation and use: Send the current owner name whenever more than one RRset of this type could exist.

typeRequired
Send in
Query string or form body
Type
DNS RR type
Accepted values
A valid PowerDNS record type. The SDM editor currently offers A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, CAA, AFSDB, DNAME, DS, and HINFO
Default
No default
Example
A

Record type.

Validation and use: Must identify the RRset being changed.

old_contentOptional
Send in
Query string or form body
Type
string
Accepted values
An existing value in the RRset
Default
Empty
Example
192.0.2.10

Old value used to select the exact record.

Validation and use: Supplying old_content is the safest form when an RRset contains multiple values.

contentRequired
Send in
Query string or form body
Type
string
Accepted values
New record data valid for type
Default
No default
Example
192.0.2.20

Replacement value.

Validation and use: Use the full normalized value for compound types such as MX and SRV.

ttlOptional
Send in
Query string or form body
Type
integer
Accepted values
A positive TTL in seconds
Default
3600
Example
3600

TTL applied to the resulting RRset.

Validation and use: The compatibility wrapper sends 3600 when omitted.

disabledOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
Preserved by the service when omitted where supported
Example
false

Sets the resulting record disabled state.

Validation and use: Use an explicit true/false value. Omitting an optional boolean keeps its documented default.

proxiedOptional
Send in
Query string or form body
Type
boolean
Accepted values
true or false; compatibility forms also accept 1, 0, yes, no, on, and off
Default
Preserved/provider state when omitted
Example
false

Sets the Cloudflare proxy preference.

Validation and use: Only valid for A, AAAA, and CNAME in a Cloudflare-capable zone.

Complete request template

This template names all 9 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "record_update",
    "zone": "example.com",
    "name": "www",
    "type": "A",
    "old_content": "192.0.2.10",
    "content": "192.0.2.20",
    "ttl": 3600,
    "disabled": false,
    "proxied": false
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=record_update' \
  --data-urlencode 'zone=example.com' \
  --data-urlencode 'name=www' \
  --data-urlencode 'type=A' \
  --data-urlencode 'old_content=192.0.2.10' \
  --data-urlencode 'content=192.0.2.20' \
  --data-urlencode 'ttl=3600'

Successful result

The response reports the updated record and resulting synchronization state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Use old_content when possible, then list the RRset to prove that the intended value—not its neighbor—changed.

POST/api/v1/dns?action=record_deletepublic APIDelete a record value or RRset

What this operation does

Deletes either one matching value or the complete RRset, depending on whether content is supplied.

Endpoint

POST /api/v1/dns?action=record_delete

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires dns.records.write permission and access to the zone.

Parameters (5)

actionRequired
Send in
Query string or form body
Type
string
Accepted values
record_delete
Default
No default
Example
record_delete

Selects this operation on the compatibility endpoint.

Validation and use: Send the exact value record_delete. Action names are case-sensitive.

zoneRequired
Send in
Query string or form body
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The zone affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

nameOptional
Send in
Query string or form body
Type
string
Accepted values
@, relative label, or name inside the zone
Default
Empty
Example
www

Record owner name.

Validation and use: Send the owner name to avoid selecting the wrong RRset.

typeRequired
Send in
Query string or form body
Type
DNS RR type
Accepted values
A valid PowerDNS record type. The SDM editor currently offers A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, CAA, AFSDB, DNAME, DS, and HINFO
Default
No default
Example
A

Record type of the target RRset.

Validation and use: Combine with name and, for value deletion, content.

contentOptional
Send in
Query string or form body
Type
string
Accepted values
An exact existing record value
Default
Omitted
Example
192.0.2.10

Selects one value for deletion.

Validation and use: If omitted, SDM deletes the entire matching RRset. Include it when only one value should be removed.

Complete request template

This template names all 5 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {
    "action": "record_delete",
    "zone": "example.com",
    "name": "www",
    "type": "A",
    "content": "192.0.2.10"
  }
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/v1/dns' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'action=record_delete' \
  --data-urlencode 'zone=example.com' \
  --data-urlencode 'name=www' \
  --data-urlencode 'type=A' \
  --data-urlencode 'content=192.0.2.10'

Successful result

The response confirms the removed value or RRset and reports synchronization state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Omitting content broadens the deletion to the entire RRset. That is useful when intentional and memorable when accidental.

GET/api/external/cloudflare/domainspublic APIList Cloudflare-managed domains

What this operation does

Lists Cloudflare-capable domains owned by the API identity, including provider and synchronization state.

Endpoint

GET /api/external/cloudflare/domains

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zones.read permission and domain ownership.

Parameters (3)

limitOptional
Send in
Query string
Type
integer
Accepted values
1 to 5000 after service normalization
Default
500
Example
100

Maximum domains returned.

Validation and use: Use bounded pagination for integrations.

offsetOptional
Send in
Query string
Type
integer
Accepted values
0 or greater
Default
0
Example
0

Number of matching domains to skip.

Validation and use: Advance from the returned offset and limit.

searchOptional
Send in
Query string
Type
string
Accepted values
A domain-name fragment
Default
Empty
Example
example

Filters the owned-domain list.

Validation and use: Search never expands the caller's ownership scope.

Complete request template

This template names all 3 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {},
  "query_parameters": {
    "limit": 100,
    "offset": 0,
    "search": "example"
  },
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/external/cloudflare/domains?limit=100&offset=0&search=example' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains total, limit, offset, supported settings, and the matching domains array.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

This is the best discovery call before using a domain path or record id in the remaining Cloudflare operations.

GET/api/external/cloudflare/domains/{domain}/statuspublic APIRead domain provider status

What this operation does

Returns local and desired DNS provider state, Cloudflare identifiers, nameservers, delegation status, and recent synchronization information for one owned domain.

Endpoint

GET /api/external/cloudflare/domains/{domain}/status

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zones.read permission and ownership of domain.

Parameters (1)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 1 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/status' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response describes the active and desired provider plus Cloudflare/delegation state for the domain.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Read status before sync, enable, disable, settings, or purge. Live Cloudflare controls may be paused when public delegation does not match assigned nameservers.

POST/api/external/cloudflare/domains/{domain}/syncpublic APISynchronize a domain to its desired provider

What this operation does

Reconciles the owned local zone with its current desired DNS provider.

Endpoint

POST /api/external/cloudflare/domains/{domain}/sync

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zones.write permission and ownership of domain.

Parameters (1)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 1 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/sync' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{}'

Successful result

The response reports the desired provider and the resulting synchronization job/state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Sync follows provider_desired; it does not silently choose Cloudflare. Read status first if the intended provider is uncertain.

POST/api/external/cloudflare/domains/{domain}/enablepublic APIEnable Cloudflare for a domain

What this operation does

Creates or locates the Cloudflare zone, synchronizes DNS records, records the desired provider, and optionally updates WHMCS-controlled nameservers.

Endpoint

POST /api/external/cloudflare/domains/{domain}/enable

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zones.write permission, ownership of domain, and a configured Cloudflare integration.

Parameters (4)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

registered_with_usOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
false
Example
false

Marks that registrar control is expected through the configured WHMCS integration.

Validation and use: When true, WHMCS validation becomes required if WHMCS automation is enabled.

client_idOptional
Send in
JSON body
Type
integer
Accepted values
A positive WHMCS client id
Default
Omitted
Example
123

Narrows WHMCS validation to one client.

Validation and use: When supplied, the returned WHMCS domain must belong to this client.

whmcs_domain_idOptional
Send in
JSON body
Type
integer
Accepted values
A positive WHMCS domain id
Default
Omitted
Example
456

Narrows WHMCS validation to one domain record.

Validation and use: When supplied, the WHMCS domain id must match the requested domain.

Complete request template

This template names all 4 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "registered_with_us": false,
    "client_id": 123,
    "whmcs_domain_id": 456
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/enable' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"registered_with_us":false}'

Successful result

The response returns Cloudflare status, zone id, assigned nameservers, WHMCS update result, and job id.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Cloudflare enablement changes the desired provider but public delegation still has to reach the assigned nameservers. WHMCS ids are validation constraints, not arbitrary metadata.

POST/api/external/cloudflare/domains/{domain}/disablepublic APIDisable Cloudflare and return to local DNS

What this operation does

Sets the desired provider to local, deletes the Cloudflare zone when one exists, and optionally restores nameservers through WHMCS automation.

Endpoint

POST /api/external/cloudflare/domains/{domain}/disable

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zones.write permission and ownership of domain.

Parameters (6)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

delete_cloudflare_zoneConditional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
false
Example
false

Confirms that the linked Cloudflare zone may be deleted.

Validation and use: Required as true when a Cloudflare zone exists.

cloudflare_delete_confirmConditional
Send in
JSON body
Type
string
Accepted values
The exact domain path value
Default
Omitted
Example
example.com

Exact-text confirmation for Cloudflare zone deletion.

Validation and use: Required with delete_cloudflare_zone=true when a linked Cloudflare zone exists.

registered_with_usOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
false
Example
false

Requests WHMCS domain control validation for registrar nameserver restoration.

Validation and use: Relevant only when WHMCS automation is enabled.

client_idOptional
Send in
JSON body
Type
integer
Accepted values
A positive WHMCS client id
Default
Omitted
Example
123

Narrows WHMCS validation to one client.

Validation and use: Must match the WHMCS domain owner when supplied.

whmcs_domain_idOptional
Send in
JSON body
Type
integer
Accepted values
A positive WHMCS domain id
Default
Omitted
Example
456

Narrows WHMCS validation to one WHMCS domain.

Validation and use: Must match the requested domain when supplied.

Complete request template

This template names all 6 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "delete_cloudflare_zone": false,
    "cloudflare_delete_confirm": "example.com",
    "registered_with_us": false,
    "client_id": 123,
    "whmcs_domain_id": 456
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/disable' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"delete_cloudflare_zone":true,"cloudflare_delete_confirm":"example.com"}'

Successful result

The response reports local provider state, whether the Cloudflare zone was deleted or already absent, local nameservers, WHMCS result, and job id.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Plan delegation before disabling. Deleting the provider zone while a registrar still delegates to it causes an outage, however sincere the JSON confirmation was.

GET/api/external/cloudflare/domains/{domain}/settingspublic APIRead supported Cloudflare settings

What this operation does

Returns the five allowlisted live settings and whether each one is available and editable for the owned domain.

Endpoint

GET /api/external/cloudflare/domains/{domain}/settings

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zone_settings.read permission and ownership of domain.

Parameters (1)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

Complete request template

This template names all 1 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/settings' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response lists development_mode, security_level, cache_level, always_online, and brotli with current values, options, editability, and delegation state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Use this read before a patch. A setting can be supported by SDM yet temporarily unavailable from Cloudflare or blocked by delegation mismatch.

PATCH/api/external/cloudflare/domains/{domain}/settings/{setting}public APIUpdate one Cloudflare setting

What this operation does

Changes exactly one allowlisted setting for an owned, correctly delegated Cloudflare zone.

Endpoint

PATCH /api/external/cloudflare/domains/{domain}/settings/{setting}

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.zone_settings.write permission and ownership of domain.

Parameters (3)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

settingRequired
Send in
URL path
Type
enum
Accepted values
development_mode, security_level, cache_level, always_online, or brotli
Default
No default
Example
security_level

Setting identifier.

Validation and use: The value must belong to the selected setting's option set.

valueRequired
Send in
JSON body
Type
enum by setting
Accepted values
development_mode: on|off; security_level: essentially_off|low|medium|high|under_attack; cache_level: basic|simplified|aggressive; always_online: on|off; brotli: on|off
Default
No default
Example
high

New setting value.

Validation and use: Send one JSON value. Unsupported setting/value pairs are rejected.

Complete request template

This template names all 3 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com",
    "setting": "security_level"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "value": "high"
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X PATCH 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/settings/security_level' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"value":"high"}'

Successful result

The response identifies the domain and returns the updated setting with its current value and Cloudflare metadata.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Under Attack is the security_level value under_attack. Turn it off by selecting an explicit normal level, usually medium, rather than guessing what the previous value was.

POST/api/external/cloudflare/domains/{domain}/cache/purgepublic APIPurge Cloudflare cache

What this operation does

Purges exactly one target class: the entire zone, files, hosts, cache tags, or URL prefixes.

Endpoint

POST /api/external/cloudflare/domains/{domain}/cache/purge

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.cache.purge permission, ownership of domain, an active Cloudflare zone id, and matching public delegation.

Parameters (6)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

purge_everythingConditional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
false
Example
false

Purges the full Cloudflare cache for the zone.

Validation and use: Choose exactly one of purge_everything=true, files, hosts, tags, or prefixes.

filesConditional
Send in
JSON body
Type
array of strings
Accepted values
1 to 100 file URLs without control characters
Default
Omitted
Example
["https://example.com/assets/app.css"]

Purges specific URLs.

Validation and use: Mutually exclusive with every other purge target.

hostsConditional
Send in
JSON body
Type
array of strings
Accepted values
1 to 100 hostnames without control characters
Default
Omitted
Example
["www.example.com"]

Purges cached content for selected hosts.

Validation and use: Mutually exclusive with every other purge target.

tagsConditional
Send in
JSON body
Type
array of strings
Accepted values
1 to 100 cache tags without control characters
Default
Omitted
Example
["catalog"]

Purges objects carrying selected cache tags.

Validation and use: Requires a Cloudflare plan/feature that supports tag purge and is mutually exclusive with other targets.

prefixesConditional
Send in
JSON body
Type
array of strings
Accepted values
1 to 100 URL prefixes without control characters
Default
Omitted
Example
["https://example.com/images/"]

Purges objects under selected prefixes.

Validation and use: Requires provider support and is mutually exclusive with other targets.

Complete request template

This template names all 6 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "purge_everything": false,
    "files": [
      "https://example.com/assets/app.css"
    ],
    "hosts": [
      "www.example.com"
    ],
    "tags": [
      "catalog"
    ],
    "prefixes": [
      "https://example.com/images/"
    ]
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/cache/purge' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"files":["https://example.com/assets/app.css"]}'

Successful result

The response identifies the purge type and returns Cloudflare's accepted purge result.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Use the narrowest target that fixes the problem. purge_everything is effective, but it also asks every cache miss to become your origin's problem at once.

GET/api/external/cloudflare/domains/{domain}/recordspublic APIList DNS records for a Cloudflare-capable domain

What this operation does

Returns local authoritative records and their Cloudflare mapping/proxy state for one owned domain.

Endpoint

GET /api/external/cloudflare/domains/{domain}/records

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.records.read permission and ownership of domain.

Parameters (3)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

limitOptional
Send in
Query string
Type
integer
Accepted values
1 to 5000 after service normalization
Default
1000
Example
500

Maximum records returned.

Validation and use: Use pagination for large zones.

offsetOptional
Send in
Query string
Type
integer
Accepted values
0 or greater
Default
0
Example
0

Records to skip.

Validation and use: Advance by the returned limit.

Complete request template

This template names all 3 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {
    "limit": 500,
    "offset": 0
  },
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/records?limit=500&offset=0' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response contains provider state, total, limit, offset, and records with local id, Cloudflare id, TTL, disabled, priority, and proxied values where available.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

Use the local numeric record id returned here in the PATCH and DELETE paths; do not substitute a Cloudflare string id.

POST/api/external/cloudflare/domains/{domain}/recordspublic APICreate and synchronize a DNS record

What this operation does

Adds a local authoritative record and immediately synchronizes its RRset to Cloudflare when the domain is Cloudflare-capable.

Endpoint

POST /api/external/cloudflare/domains/{domain}/records

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.records.write permission and ownership of domain.

Parameters (9)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

nameOptional
Send in
JSON body
Type
string
Accepted values
@, a relative label, or a name inside domain
Default
@
Example
www

Record owner name.

Validation and use: SDM normalizes the name into the domain.

typeRequired
Send in
JSON body
Type
DNS RR type
Accepted values
A valid PowerDNS record type. The SDM editor currently offers A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, CAA, AFSDB, DNAME, DS, and HINFO
Default
No default
Example
A

Record type.

Validation and use: Cloudflare proxying is restricted to A, AAAA, and CNAME.

contentRequired
Send in
JSON body
Type
string
Accepted values
Record data valid for type
Default
No default
Example
192.0.2.10

Record content.

Validation and use: For MX, content may be a destination hostname and priority/prio will be prepended, or content may already contain both priority and destination.

priorityOptional
Send in
JSON body
Type
integer
Accepted values
A positive MX priority
Default
Omitted
Example
10

Preferred MX priority key.

Validation and use: Used for MX only. If content already starts with a numeric priority, it is not added again.

prioOptional
Send in
JSON body
Type
integer
Accepted values
A positive MX priority
Default
Omitted
Example
10

Compatibility alias for priority.

Validation and use: Use priority for new integrations. It takes precedence when both keys are supplied.

ttlOptional
Send in
JSON body
Type
integer
Accepted values
A positive TTL in seconds
Default
3600
Example
3600

Record TTL.

Validation and use: A non-positive or missing value becomes 3600.

disabledOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
false
Example
false

Creates the record disabled when true.

Validation and use: Use an explicit true/false value. Omitting an optional boolean keeps its documented default.

proxiedOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
Provider/default state when omitted
Example
false

Requests Cloudflare proxying.

Validation and use: Valid only for A, AAAA, and CNAME.

Complete request template

This template names all 9 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com"
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "name": "www",
    "type": "A",
    "content": "192.0.2.10",
    "priority": 10,
    "prio": 10,
    "ttl": 3600,
    "disabled": false,
    "proxied": false
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X POST 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/records' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"name":"www","type":"A","content":"192.0.2.10","ttl":3600,"disabled":false,"proxied":true}'

Successful result

The response returns the created local record and the Cloudflare synchronization result.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

The write is local-authoritative first and then provider-synchronized. Treat a sync error as an incomplete operation and read both record and domain status before retrying.

PATCH/api/external/cloudflare/domains/{domain}/records/{record_id}public APIUpdate and synchronize one DNS record

What this operation does

Loads the current local record by id, preserves omitted fields, applies supplied changes, and synchronizes the old and new RRsets as needed.

Endpoint

PATCH /api/external/cloudflare/domains/{domain}/records/{record_id}

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.records.write permission and ownership of domain.

Parameters (10)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

record_idRequired
Send in
URL path
Type
integer
Accepted values
A positive local record id returned by the list operation
Default
No default
Example
42

Local SDM record identifier.

Validation and use: It must belong to domain.

nameOptional
Send in
JSON body
Type
string
Accepted values
@, relative label, or name inside domain
Default
Current name
Example
api

Replacement owner name.

Validation and use: Omit to preserve the current name.

typeOptional
Send in
JSON body
Type
DNS RR type
Accepted values
A valid PowerDNS record type. The SDM editor currently offers A, AAAA, CNAME, MX, TXT, NS, PTR, SRV, CAA, AFSDB, DNAME, DS, and HINFO
Default
Current type
Example
AAAA

Replacement record type.

Validation and use: Omit to preserve the current type. Proxy validation uses the resulting type.

contentOptional
Send in
JSON body
Type
string
Accepted values
Record data valid for the resulting type
Default
Current content
Example
2001:db8::10

Replacement content.

Validation and use: Omit to preserve current content. For MX, priority/prio can be prepended when content lacks one.

priorityOptional
Send in
JSON body
Type
integer
Accepted values
A positive MX priority
Default
Omitted/current content
Example
10

Preferred MX priority key.

Validation and use: Used only when the resulting type is MX.

prioOptional
Send in
JSON body
Type
integer
Accepted values
A positive MX priority
Default
Omitted/current content
Example
10

Compatibility alias for priority.

Validation and use: Use priority for new clients.

ttlOptional
Send in
JSON body
Type
integer
Accepted values
A positive TTL in seconds
Default
Current TTL
Example
3600

Replacement TTL.

Validation and use: Omit or send a non-positive value to preserve the current TTL.

disabledOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
Current disabled state
Example
false

Replacement disabled state.

Validation and use: Use an explicit true/false value. Omitting an optional boolean keeps its documented default.

proxiedOptional
Send in
JSON body
Type
boolean
Accepted values
JSON true or false
Default
Current proxy preference
Example
false

Replacement Cloudflare proxy preference.

Validation and use: Valid only when the resulting type is A, AAAA, or CNAME.

Complete request template

This template names all 10 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com",
    "record_id": 42
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {
    "name": "api",
    "type": "AAAA",
    "content": "2001:db8::10",
    "priority": 10,
    "prio": 10,
    "ttl": 3600,
    "disabled": false,
    "proxied": false
  },
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X PATCH 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/records/42' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"content":"192.0.2.20","ttl":3600}'

Successful result

The response returns the resulting record and synchronization state.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

At least one meaningful field should be supplied. Read the current record first; omitted fields are preserved, which is convenient until a stale client assumes otherwise.

DELETE/api/external/cloudflare/domains/{domain}/records/{record_id}public APIDelete and synchronize one DNS record

What this operation does

Deletes the local record selected by id and synchronizes the remaining RRset to Cloudflare.

Endpoint

DELETE /api/external/cloudflare/domains/{domain}/records/{record_id}

Authentication and permissions

Send X-API-Name and X-API-Key, or use HTTP Basic authentication. Requires cloudflare.records.write permission and ownership of domain.

Parameters (2)

domainRequired
Send in
URL path
Type
string
Accepted values
A valid DNS zone name, with or without a final dot
Default
No default
Example
example.com

The domain affected by the request.

Validation and use: The authenticated API user must own the zone unless the operation creates it for that same user.

record_idRequired
Send in
URL path
Type
integer
Accepted values
A positive local record id returned by the list operation
Default
No default
Example
42

Local SDM record identifier.

Validation and use: It must belong to domain.

Complete request template

This template names all 2 supported path, query, form, and JSON keys. Conditional alternatives are shown together for reference; keep only the valid branch in a runnable request.

{
  "path_parameters": {
    "domain": "example.com",
    "record_id": 42
  },
  "query_parameters": {},
  "form_body": {},
  "json_body": {},
  "query_or_form_parameters": {}
}

Runnable workflow example

curl -sS -X DELETE 'https://panel.example.com:882/api/external/cloudflare/domains/example.com/records/42' \
  -H 'X-API-Name: dns-automation' \
  -H 'X-API-Key: YOUR_API_KEY'

Successful result

The response confirms record_id and returns the Cloudflare synchronization result.

Error response

{
  "success": false,
  "error": {
    "code": "external_auth_error",
    "message": "Authentication failed, the source address is not allowed, the permission is missing, or the requested resource is outside this API user's ownership."
  }
}

Operational note

List the record immediately before deletion and list again afterward. Record ids are local identifiers and may change when a record is recreated.

Compatibility aliases

Use the clean routes above for new integrations. The following public aliases remain accepted for existing clients. They do not create extra capabilities; each one maps to the complete operation card named in the last column.

Public aliasMethod and complete location changesUse this full contract
/api/v1/dns/externalGET or POST. Send the same action and action-specific query/form keys as /api/v1/dns.All 18 DNS compatibility cards.
POST /api/external/cloudflare/enableMove domain from the path into JSON. JSON keys: domain, registered_with_us, client_id, whmcs_domain_id.Enable Cloudflare.
POST /api/external/cloudflare/disableMove domain into JSON. JSON keys: domain, delete_cloudflare_zone, cloudflare_delete_confirm, registered_with_us, client_id, whmcs_domain_id.Disable Cloudflare.
GET /api/external/domain/statusQuery key domain; name is an accepted alias when domain is absent.Read domain provider status.
POST /api/external/domain/syncJSON key domain.Synchronize a domain.

Direct-wrapper compatibility

Older deployments may call /api/external/cloudflare.php directly. Keep these only while migrating an existing client:

  • ?action=domains or list: GET query keys limit (500), offset (0), and search.
  • ?action=zone-settings, zone_settings, or settings: GET query domain or its alias name.
  • ?action=zone-setting, zone_setting, or setting: POST query domain/name; JSON setting and value with the same five setting/value sets shown above.
  • ?action=purge-cache, purge_cache, or purge: POST query domain/name; JSON chooses exactly one of purge_everything, files, hosts, tags, or prefixes.
  • ?action=action: POST query domain/name and JSON action. Accepted action aliases are enable_development_mode, development_mode_on, dev_mode_on, disable_cache, cache_bypass_on, disable_development_mode, development_mode_off, dev_mode_off, enable_cache, cache_bypass_off, enable_under_attack, under_attack_on, disable_under_attack, under_attack_off, set_security_level, set_cache_level, always_online_on, enable_always_online, always_online_off, disable_always_online, brotli_on, enable_brotli, brotli_off, disable_brotli, purge_cache, and purge_everything. Optional keys are fallback_security_level (default medium when disabling Under Attack), value, security_level, cache_level, and the five purge-target keys. For new clients, use the clean setting or purge routes instead.

Errors and safe retries

HTTP resultTypical meaningNext step
400Missing, malformed, unsupported, or mutually incompatible parameters.Compare the request with the complete template and the conditional rules.
401Missing/invalid credentials, inactive linked panel account, or blocked external identity.Check both account states, key rotation, and the authentication method.
403Permission, ownership, source-IP, or reserved-root boundary.Use the correct API user and source; do not try to turn an ownership error into a retry loop.
404The public route, owned domain, zone, or record id was not found.Confirm the port and public path, then rediscover current resource ids.
409Safety confirmation, provider/delegation state, DNSSEC sequence, or concurrent mutation conflict.Read current state and satisfy the stated prerequisite before retrying.
413The complete zone file exceeded 16 MiB.Stop and validate the source artifact instead of splitting one logical replacement into unsafe partial writes.
5xxDatabase, authoritative DNS, provider, or synchronization work did not complete.Preserve the response, read current state, and retry only when the operation is proven idempotent.

How to use it

  1. Call ping from the integration's real source address.
  2. Use a list/status operation to discover the owned zone, domain, or record id.
  3. Open the operation card and account for every parameter in its complete template.
  4. Build one valid branch, omitting mutually exclusive alternatives.
  5. Send the request once, inspect both HTTP status and JSON, then verify with the corresponding read operation.

Result and next check

A correct integration reaches https://panel.example.com:882, authenticates as a dedicated non-root API user, supplies every key required by its chosen workflow, and remains within its owned DNS scope. After any write, confirm the authoritative record or DNSSEC/provider state instead of treating a successful HTTP exchange as the end of the story.

Theme color