Beta API

DNScale DNS Control is currently a read-only public beta API. It can connect to supported authoritative DNS providers, list zones, save inventory, capture snapshots, and compare snapshots. It does not write records back to external providers.

Overview

DNScale DNS Control gives you a reproducible view of authoritative DNS state across providers. Use it to:

Discover supported provider adapters and their required auth fields.
Register read-only provider connections.
List zones from a connected provider.
Save a zone into DNScale inventory.
Capture immutable snapshots.
Compare snapshots for added, removed, changed, and provider-specific drift.

The API is catalog-driven. Call /dns-sources/providers first, then use the returned type, auth_type, and auth_fields to build a provider connection request.

Boundaries

This API does not provide:

Provider write-back.
Automatic sync or apply jobs.
AXFR/IXFR zone-transfer automation.
Live authoritative failover by itself.

Provider-specific warnings are returned as capability metadata where they matter. Portable DNS changes and provider-only metadata changes are reported separately in snapshot diffs.

Security Model

Provider credential fields are accepted when you create a connection. DNScale validates the credentials and stores encrypted credential data and metadata only.

Responses never include:

Provider API tokens.
Secret access keys.
Encrypted credential blobs.
Credential storage backend names.
Raw provider payloads.

Required Scopes

Use zones:read for read operations and zones:write for creating provider connections, saving inventory, and capturing snapshots.

Provider Catalog

curl "https://api.dnscale.eu/v1/dns-sources/providers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "status": "success",
  "data": {
    "providers": [
      {
        "type": "route53",
        "name": "Amazon Route 53",
        "description": "Inventory zones from AWS Route 53 through the API",
        "auth_type": "access_keys",
        "auth_fields": [
          { "name": "access_key_id", "type": "text", "required": true },
          { "name": "secret_access_key", "type": "password", "required": true },
          { "name": "region", "type": "text", "required": false }
        ],
        "capabilities": {
          "can_list_zones": true,
          "can_read_records": true,
          "can_write_records": false,
          "supports_alias_flattening": true,
          "exposes_assigned_nameservers": true
        },
        "warnings": [
          "Some provider-specific routing metadata may not be portable DNS state."
        ]
      }
    ]
  }
}

Create Provider Connection

Create provider connections with read-only provider credentials. The response is redacted and does not return the submitted credentials or credential storage details.

Use the provider type and credential field names returned by the provider catalog:

curl -X POST "https://api.dnscale.eu/v1/dns-sources/connections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "route53",
    "name": "Production authoritative DNS",
    "mode": "read_only",
    "credentials": {
      "access_key_id": "ACCESS_KEY_ID",
      "secret_access_key": "SECRET_ACCESS_KEY",
      "region": "us-east-1"
    }
  }'

Example redacted response:

{
  "status": "success",
  "data": {
    "connection": {
      "id": "0e47f95a-4ad8-4b2e-a02b-b204bf1bb5b9",
      "provider": "route53",
      "name": "Production authoritative DNS",
      "mode": "read_only",
      "scopes": ["zones:read"],
      "status": "verified",
      "capabilities": {
        "can_list_zones": true,
        "can_read_records": true,
        "can_write_records": false
      },
      "last_verified_at": "2026-08-05T10:00:00Z",
      "last_successful_inventory_at": null,
      "disabled_at": null,
      "created_at": "2026-08-05T10:00:00Z",
      "updated_at": "2026-08-05T10:00:00Z"
    }
  }
}

List Provider Connections

curl "https://api.dnscale.eu/v1/dns-sources/connections" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Provider Zones

curl "https://api.dnscale.eu/v1/dns-sources/connections/{connection_id}/zones" \
  -H "Authorization: Bearer YOUR_API_KEY"

The provider zones response includes provider-assigned nameservers and DNSSEC metadata where the connected provider exposes them.

Save Zone Inventory

Save a provider zone as a tracked DNScale inventory item:

curl -X POST "https://api.dnscale.eu/v1/dns-sources/connections/{connection_id}/zones/{external_zone_id}/inventory" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_name": "example.com"
  }'

Capture Snapshot

Capture a new immutable snapshot directly from a connected provider zone:

curl -X POST "https://api.dnscale.eu/v1/dns-sources/connections/{connection_id}/zones/{external_zone_id}/snapshots" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_name": "example.com"
  }'

If inventory already exists, you can capture by inventory ID:

curl -X POST "https://api.dnscale.eu/v1/dns-inventory/{inventory_id}/snapshots" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Inventory And Snapshots

curl "https://api.dnscale.eu/v1/dns-inventory" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
curl "https://api.dnscale.eu/v1/dns-inventory/{inventory_id}/snapshots?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Snapshot

curl "https://api.dnscale.eu/v1/dns-inventory/{inventory_id}/snapshots/{snapshot_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Snapshot responses include normalized record sets:

{
  "id": "snapshot_uuid",
  "zone_inventory_id": "inventory_uuid",
  "captured_at": "2026-08-05T10:00:00Z",
  "source_kind": "provider_api",
  "source_version": "dnscale.dns_state.v1",
  "record_set_count": 1,
  "portable_hash": "sha256...",
  "provider_hash": "sha256...",
  "record_sets": [
    {
      "record_set_key": "example.com.|www.example.com.|A|IN|default",
      "owner_name": "www.example.com.",
      "rrtype": "A",
      "dns_class": "IN",
      "routing_policy_key": "default",
      "ttl": 300,
      "values": [{ "value": "192.0.2.10" }],
      "provider_metadata": {
        "routing_policy": { "type": "default" }
      },
      "unsupported": false,
      "warnings": []
    }
  ]
}

Diff Snapshots

curl "https://api.dnscale.eu/v1/dns-inventory/{inventory_id}/snapshots/{from_snapshot_id}/diff/{to_snapshot_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Diff changes are grouped as:

Type	Meaning
`added_record_set`	The RRSet exists only in the target snapshot
`removed_record_set`	The RRSet exists only in the source snapshot
`value_changed`	DNS answer values changed
`ttl_changed`	TTL changed while values stayed the same
`provider_metadata_changed`	Provider-specific metadata changed without a portable DNS answer change

Provider-specific changes can be important for review, but they are separate from portable DNS answer changes.