Introducing the DNScale Python SDK

The official DNScale Python SDK 1.0.0 is available on PyPI. Install dnscale, supply an API key, and manage zones and records directly from Python.

The SDK supports Python 3.10 and newer, with synchronous and asynchronous calls. Its source code is public on GitHub.

DNS automation inside your application

Terraform and DNSControl are useful when DNS configuration lives in a repository and changes go through a preview-and-apply workflow. An SDK serves a different need: DNS operations that happen inside your application or script.

That might be a tenant-onboarding service creating a verification record, a background job inventorying zones, or an internal tool provisioning a test environment. You can already build these workflows with the REST API. The Python SDK gives them a shared client with typed request and response models, pagination helpers, and structured API errors.

The API remains the foundation. The SDK uses the same credentials, permissions, and endpoints; it does not introduce a separate account or bypass API limits.

Start with a read-only request

Install the package in your Python environment:

python -m pip install dnscale

Create an API key with zones:read permission in the dashboard and make it available through the DNSCALE_API_KEY environment variable. Keep the key in your secret manager or local environment, not in source code. See the authentication documentation for scopes and zone restrictions.

from dnscale import DNScale
 
with DNScale() as dns:
    for zone in dns.zones.iter():
        print(zone.id, zone.name)

DNScale() reads the API key from the environment. The iterator fetches additional pages as needed, and the context manager closes the client when the script finishes.

Create a record when your workflow needs it

For a write example, set DNSCALE_ZONE_ID to the UUID of a test zone you control. The key needs zones:read and records:write, with access to that zone and record name.

This example creates a real TXT record. Replace the example value with the value required by your own verification workflow, and use a name that is not managed by another tool.

import os
 
from dnscale import DNScale
 
with DNScale() as dns:
    record = dns.records.create(
        os.environ["DNSCALE_ZONE_ID"],
        name="_sdk-demo",
        type_="TXT",
        content="dnscale-sdk-example",
        ttl=300,
    )
    print(record.id, record.name, record.content)

Save the returned record ID if you need to update or remove it later. The Python SDK guide walks through the complete create, update, and delete lifecycle, including the new ID returned after an update.

What is included in 1.0.0?

• Zone and record helpers for creating, listing, reading, updating, and deleting resources.
• Pagination iterators for walking zones and records without manually maintaining offsets.
• Async equivalents for application code using async and await.
• Structured API exceptions, including rate-limit errors and request IDs when provided by the API.
• Bounded retries for safe reads. Mutations are not automatically retried, so a failed connection does not silently trigger another create or update.
• Generated API access through the included dnscale_api package for the wider OpenAPI contract, including DNSSEC, usage, billing, and account operations.

An SDK is not a desired-state engine. It does not provide Terraform-style plans, automatic rollback, or drift reconciliation. If a write times out, inspect the resulting state before deciding whether to repeat it. Keep one routine owner for each record set so application code and infrastructure tooling do not overwrite each other's changes.

Pick the right integration

Use the Python SDK for Python applications and procedural automation. Use Terraform for infrastructure-managed DNS, or DNSControl for DNS-focused configuration workflows. The REST API remains available for any language and custom HTTP client.

Python is the first SDK covered in our new SDKs learning section. Start with the guide, consult the zone and record references for endpoint details, and report SDK issues or requests on GitHub.