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 — SSL mode, cache level, development mode, and the security/traffic features your plan entitles.

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

Get zone settings

Current edge settings for the zone, plus which features the plan entitles.

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	flexible \| full \| strict.
cache_level	string	bypass \| standard \| cache_everything.
dev_mode	boolean	Temporarily bypass the cache for the whole zone.
rocket_cache	boolean	Pre-warm observed URLs (plan-gated).

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"}'

This is a subset of the available settings; the GET response lists every field and its allowed values.

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.