API documentation

The CloudArya REST API manages zones, DNS records, and CDN cache from your own tooling — CI pipelines, the WHMCS module, or a script. All requests are JSON over HTTPS.

Base URL

https://api.cloudarya.com/api/v1

Authentication

Every request carries a bearer token in the Authorization header. Mint one in the dashboard under API Tokens — grant only the abilities a consumer needs, and optionally scope it to specific zones.

Authorization: Bearer YOUR_TOKEN

Abilities

A token grants a subset of these. Requests needing an ability the token lacks return 403.

zone:read	Read zones	List and read zones in the account.
zone:create	Create zones	Add a new zone. Account-level — not available on a zone-scoped token.
zone:delete	Delete zones	Remove a zone. Account-level — not available on a zone-scoped token.
dns:read	Read records	List DNS records, zone settings, analytics, and exports.
dns:write	Edit records	Create, update, delete records; edit zone settings; import.
cache:purge	Purge cache	Queue CDN cache purges for proxied hosts.

Zone scope

A token can be limited to one or more zones. A zone-scoped token cannot use the account-level abilities (zone:create, zone:delete) and returns 403 for any zone outside its scope. Leaving the scope empty grants access to every zone in the account.

Conventions

Send and accept application/json. List endpoints wrap results in a { "data": [...] } envelope.
The account slug is part of the path: /accounts/{account}/…. The zone name is passed as {domain}.
Validation failures return 422 with an errors object keyed by field.
Supported record types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, LUA. Proxying (the CDN edge) applies to A, AAAA, and CNAME.

Status codes

200	OK — the request succeeded.
201	Created — a new resource was created.
202	Accepted — queued for asynchronous processing (e.g. a cache purge).
401	Unauthenticated — missing or invalid token.
403	Forbidden — the token lacks the required ability, or the zone is out of its scope.
404	Not found — no such account, zone, or record.
422	Validation error — the body failed validation; see the `errors` object.
429	Too many requests — you hit a rate limit; retry after a short wait.

Zones

A zone is a domain you manage through CloudArya. The account slug and zone name appear in the path; a token may be scoped to specific zones.

GET/accounts/{account}/zones

List zones

Every zone in the account (or those the token is scoped to).

Requires ability: zone:read

Path parameters

account

string

Your account slug, e.g. google.

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones \
  -H "Authorization: Bearer {TOKEN}"

Response — 200

{
  "data": [
    {
      "id": 62,
      "domain": "example.com",
      "status": "active",
      "nameservers": ["ns1.cloudarya.com", "ns2.cloudarya.com"],
      "pending_records": 0,
      "failed_records": 0
    }
  ]
}

The zone name is returned as `domain`.

POST/accounts/{account}/zones

Create a zone

Add a zone to the account. Idempotent — an existing zone is returned with 200.

Requires ability: zone:create

Body

domain*

string

The apex domain, e.g. example.com.

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/zones \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Response — 201

{ "data": { "id": 62, "domain": "example.com", "status": "active",
  "nameservers": ["ns1.cloudarya.com", "ns2.cloudarya.com"] } }

GET/accounts/{account}/zones/{domain}

Get a zone

A single zone by name.

Requires ability: zone:read

Path parameters

account	string	Account slug.
domain	string	Zone name, e.g. example.com.

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com \
  -H "Authorization: Bearer {TOKEN}"

DELETE/accounts/{account}/zones/{domain}

Delete a zone

Remove a zone and all of its records.

Requires ability: zone:delete

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com \
  -H "Authorization: Bearer {TOKEN}"

DNS records

Records live under a zone. Supported types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, LUA. A/AAAA/CNAME records can be proxied through the CDN edge ("orange cloud").

GET/accounts/{account}/zones/{domain}/records

List records

All records in the zone, ordered by name then type.

Requires ability: dns:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/records \
  -H "Authorization: Bearer {TOKEN}"

Response — 200

{
  "data": [
    {
      "id": 1024, "type": "A", "name": "@", "content": "203.0.113.10",
      "ttl": 3600, "priority": null, "proxied": true, "proxiable": true,
      "sync_status": "synced"
    }
  ]
}

POST/accounts/{account}/zones/{domain}/records

Create a record

Add a DNS record to the zone.

Requires ability: dns:write

Body

type*	string	One of A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, LUA.
name	string	The host, relative to the zone. Omit or use "@" for the apex. Default "@".
content*	string	The record value (IP, hostname, text, …).
ttl	integer	Time-to-live in seconds. Optional; the zone default is used when omitted.
priority	integer	Priority for MX/SRV records. 0–65535.
proxied	boolean	Route through the CDN edge. Only honored for A/AAAA/CNAME; ignored otherwise.

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/records \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","name":"www","content":"203.0.113.10","proxied":true}'

Response — 201

{ "data": { "id": 1025, "type": "A", "name": "www", "content": "203.0.113.10",
  "proxied": true, "sync_status": "pending" } }

PUT/accounts/{account}/zones/{domain}/records/{id}

Update a record

Change fields on a record. PATCH is accepted as an alias; send only the fields you want to change.

Requires ability: dns:write

Path parameters

string

Numeric record id (from the list endpoint).

Body

type	string	New record type.
name	string	New host name.
content	string	New value.
ttl	integer	New TTL.
priority	integer	New priority (MX/SRV).
proxied	boolean	Toggle CDN proxying.

Example

curl -X PUT https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/records/1025 \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content":"203.0.113.20"}'

DELETE/accounts/{account}/zones/{domain}/records/{id}

Delete a record

Remove a record from the zone.

Requires ability: dns:write

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/records/1025 \
  -H "Authorization: Bearer {TOKEN}"

Cache purge

Queue CDN cache purges for a zone's proxied hosts. Purges are applied asynchronously by the edge nodes, so a successful call returns 202 (queued), not an immediate flush. Only names actually served through the edge can be purged.

POST/accounts/{account}/zones/{domain}/purge

Purge cache

Purge specific URLs, path prefixes, or everything. Provide at least one of "urls", "prefixes", or "everything".

Requires ability: cache:purge

Body

urls	string[]	Exact URLs to purge (max 100). Absolute URLs must target a proxied host of this zone; a bare path resolves to the zone apex. Query strings are part of the match.
prefixes	string[]	Path prefixes to purge (max 100). "/blog" clears /blog and every descendant.
everything	boolean	Purge all cached content for every proxied host in the zone. Use sparingly.

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/purge \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/style.css","https://example.com/blog/post-1"]}'

Response — 202

{ "data": { "queued": 2 } }

Prefer scoping a cache-purge token to a single zone and granting only the cache:purge ability.
422 is returned if the zone has no proxied records, or if none of urls/prefixes/everything is supplied.

Zone settings

Per-zone CDN edge behavior in one resource: TLS/origin (ssl_mode, hsts, min_tls), caching (cache_level, edge_ttl, cache_by_device, dev_mode, rocket_cache), optimization (image_opt, rocket_loader), WAF (waf_mode, waf_paranoia) and firewall (fw_country_mode, fw_countries, fw_ip_block, under_attack). Premium fields are gated by plan entitlements.

GET/accounts/{account}/zones/{domain}/proxy-settings

Get zone settings

Every current edge setting for the zone (all fields listed under the update endpoint), plus an entitlements map of which premium features the plan unlocks and rocket_cache_status when pre-warm is on.

Requires ability: dns:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/proxy-settings \
  -H "Authorization: Bearer {TOKEN}"

PUT/accounts/{account}/zones/{domain}/proxy-settings

Update zone settings

Change edge settings. Send only the fields you want to change; gated features return 422 without the entitlement.

Requires ability: dns:write

Body

ssl_mode	string	How the edge connects to your origin: flexible \| full \| strict. strict requires the cdn_strict_ssl entitlement.
hsts	boolean	Send Strict-Transport-Security on responses. Requires cdn_min_tls.
min_tls	string	Minimum TLS version clients may negotiate: 1.2 \| 1.3. 1.3 requires cdn_min_tls.
cache_level	string	bypass \| standard \| cache_everything. cache_everything requires cdn_cache_everything.
edge_ttl	integer	Edge cache TTL in seconds; must be one of the allowed EDGE_TTLS steps.
override_cache	boolean	Ignore the origin's Cache-Control and apply edge_ttl instead.
cache_by_device	boolean	Vary the cache key by device class (mobile/desktop/tablet). Requires cdn_cache_by_device.
dev_mode	boolean	Temporarily bypass the cache for the whole zone.
rocket_cache	boolean	Proactively pre-warm observed URLs on the edges. Requires cdn_rocket_cache.
image_opt	boolean	On-the-fly image optimization / WebP at the edge. Requires cdn_image_opt.
rocket_loader	boolean	Defer/async JavaScript to speed first paint. Requires cdn_rocket_loader.
waf_mode	string	Managed WAF ruleset: off \| log \| block. log/block require cdn_waf.
waf_paranoia	integer	WAF sensitivity: 1 (fewer false positives) or 2 (stricter).
fw_country_mode	string	Country filter mode: off \| block \| allow. block/allow require cdn_firewall.
fw_countries	string[]	ISO 3166-1 alpha-2 codes the country filter applies to (max 250).
fw_ip_block	string[]	IPv4/IPv6 addresses or CIDRs to block (max 1000).
under_attack	boolean	"Under Attack" interstitial challenge for the zone. Requires cdn_under_attack.
ip_reputation	boolean	Enforce the platform-managed IP-reputation feed (block known-bad IPs) for this zone. Requires cdn_firewall.
maintenance_mode	boolean	Park the zone: the edge serves a branded 503 maintenance page for every request (ACME challenges still pass, so certs keep renewing). Default false.
origin_offline	boolean	Always-Online: when the origin is unreachable, keep serving the last-good cached copy / a branded offline page instead of the origin's raw error. Default true.

Example

curl -X PUT https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/proxy-settings \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"cache_level":"cache_everything","min_tls":"1.3","hsts":true}'

Send only the fields you want to change — the rest are left untouched.
Premium fields return 422 with an errors.<field> message when the plan lacks the entitlement; GET proxy-settings returns the plan's entitlements map so a client can tell what's unlocked.
Changes are read by the edge nodes on their next sync (~1 min), not instantly.

Firewall rules

Per-zone allow/block rules on an IP or CIDR, evaluated at the edge in ascending priority — the first match wins. An allow is a whitelist exception (it short-circuits the firewall); a block returns 403. Requires the firewall entitlement to take effect at the edge.

GET/accounts/{account}/zones/{domain}/firewall/rules

List firewall rules

All access rules for the zone, in evaluation (priority) order.

Requires ability: dns:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/firewall/rules \
  -H "Authorization: Bearer {TOKEN}"

POST/accounts/{account}/zones/{domain}/firewall/rules

Create a firewall rule

Add an allow/block rule for an IP or CIDR.

Requires ability: dns:write

Body

action*	string	allow \| block. allow whitelists (bypasses the firewall); block returns 403.
value	string	IPv4/IPv6 address or CIDR, e.g. 203.0.113.4 or 203.0.113.0/24. Provide this OR ip_list_id.
ip_list_id	integer	Target a reusable IP list (bulklist) instead of a single value — the action applies to every member. Provide this OR value.
note	string	Optional label.
priority	integer	Evaluation order, lowest first (default 100).
enabled	boolean	Whether the rule is active (default true).

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/firewall/rules \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"action":"block","value":"203.0.113.0/24","note":"abuse","priority":10}'

PUT/accounts/{account}/zones/{domain}/firewall/rules/{rule}

Update a firewall rule

Change any field of a rule. Send only what you want to change.

Requires ability: dns:write

Example

curl -X PUT https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/firewall/rules/42 \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"priority":5,"enabled":false}'

DELETE/accounts/{account}/zones/{domain}/firewall/rules/{rule}

Delete a firewall rule

Remove a rule.

Requires ability: dns:write

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/firewall/rules/42 \
  -H "Authorization: Bearer {TOKEN}"

IP lists (bulklists)

Reusable, account-level lists of IPs/CIDRs. A firewall rule can target a list by id (via ip_list_id) instead of a single value — the edge applies the rule's action to every member — so you maintain the addresses in one place. Separately, a zone can enable the platform-managed IP-reputation feed with the ip_reputation zone setting.

GET/accounts/{account}/ip-lists

List IP lists

All bulklists in the account with their entry counts.

Requires ability: dns:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/ip-lists -H "Authorization: Bearer {TOKEN}"

POST/accounts/{account}/ip-lists

Create an IP list

Create a reusable list; reference its id from a firewall rule's ip_list_id.

Requires ability: dns:write

Body

slug*	string	Unique key within the account ([a-z0-9-]).
name*	string	Display name.

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/ip-lists \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"slug":"office","name":"Office IPs"}'

POST/accounts/{account}/ip-lists/{list}/entries

Add an entry

Add an IP or CIDR to a list.

Requires ability: dns:write

Body

value*	string	IPv4/IPv6 address or CIDR.
note	string	Optional label.

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/ip-lists/12/entries \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"value":"203.0.113.0/24"}'

DELETE/accounts/{account}/ip-lists/{list}/entries/{entry}

Remove an entry

Delete an entry from a list.

Requires ability: dns:write

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/ip-lists/12/entries/98 \
  -H "Authorization: Bearer {TOKEN}"

DELETE/accounts/{account}/ip-lists/{list}

Delete an IP list

Remove a list (and its entries). Firewall rules referencing it have the reference cleared.

Requires ability: dns:write

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/ip-lists/12 -H "Authorization: Bearer {TOKEN}"

Rate limiting

Per-zone rate-limit rules: cap requests per client IP to a matching path prefix (and optional HTTP methods) over a fixed window of seconds. When a client exceeds the threshold the edge blocks (429) or logs. Rules are evaluated in priority order; requires the firewall entitlement.

GET/accounts/{account}/zones/{domain}/rate-limits

List rate-limit rules

All rate-limit rules for the zone, in evaluation order.

Requires ability: dns:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/rate-limits \
  -H "Authorization: Bearer {TOKEN}"

POST/accounts/{account}/zones/{domain}/rate-limits

Create a rate-limit rule

Cap requests to a path over a window.

Requires ability: dns:write

Body

threshold*	integer	Max requests per client IP per window (1–1,000,000).
window*	integer	Window length in seconds (1–3600).
path	string	Path prefix the rule applies to; empty or "/" = whole site.
methods	string[]	HTTP methods to match (e.g. ["POST"]); omit/empty = any method.
action	string	block (429) \| log. Default block.
note	string	Optional label.
priority	integer	Evaluation order, lowest first (default 100).
enabled	boolean	Whether the rule is active (default true).

Example

curl -X POST https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/rate-limits \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"path":"/wp-login.php","methods":["POST"],"threshold":5,"window":300}'

PUT/accounts/{account}/zones/{domain}/rate-limits/{rule}

Update a rate-limit rule

Change any field of a rule.

Requires ability: dns:write

Example

curl -X PUT https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/rate-limits/7 \
  -H "Authorization: Bearer {TOKEN}" -H "Content-Type: application/json" \
  -d '{"threshold":20,"action":"log"}'

DELETE/accounts/{account}/zones/{domain}/rate-limits/{rule}

Delete a rate-limit rule

Remove a rule.

Requires ability: dns:write

Example

curl -X DELETE https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/rate-limits/7 \
  -H "Authorization: Bearer {TOKEN}"

Certificates

TLS certificates are issued and renewed for you (ACME dns-01) and pushed to the edges automatically — there's nothing to upload. This read-only endpoint reports what the edge is currently serving for each proxied host.

GET/accounts/{account}/zones/{domain}/certificates

List zone certificates

Live inventory of the edge TLS certificate for each proxied host: issuer, subject, SANs, validity window and days remaining. Only proxied ("orange cloud") hosts have an edge cert.

Requires ability: zone:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/certificates \
  -H "Authorization: Bearer {TOKEN}"

Response — 200

{ "data": [ { "hostname": "www.example.com", "ok": true, "issuer": "Let's Encrypt",
  "subject": "www.example.com", "sans": ["www.example.com","example.com"],
  "not_before": "2026-08-01T00:00:00+00:00", "not_after": "2026-10-30T00:00:00+00:00",
  "days_remaining": 71, "error": null } ],
  "meta": { "edge": "135.181.1.1", "proxied_hosts": 1, "probed": 1, "truncated": false } }

Read live from an edge, so it reflects the real handshake — not a stored record. error is "unreachable" if the edge didn't answer, or "cdn_disabled" if the zone has no proxied hosts / the CDN isn't active.
Capped at the first 25 proxied hosts (meta.truncated flags when there are more).

Analytics & logs

Read-only traffic and cache analytics for a zone.

GET/accounts/{account}/zones/{domain}/analytics

Zone analytics

Request, bandwidth, and cache-hit time series aggregated across the zone's proxied hosts.

Requires ability: zone:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/analytics \
  -H "Authorization: Bearer {TOKEN}"

GET/accounts/{account}/zones/{domain}/logs

Request log

Recent individual edge requests for the zone (method, path, status, cache disposition, edge node).

Requires ability: zone:read

Example

curl https://api.cloudarya.com/api/v1/accounts/{account}/zones/example.com/logs \
  -H "Authorization: Bearer {TOKEN}"

Need something not covered here? Email support@cloudarya.com.