API Overview

Base URL

https://api.dnscale.eu/v1

Authentication

Every API request requires authentication via a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are scoped to a customer account and carry permissions that control what operations they can perform. See Authentication for details.

Customer Context

The DNScale API uses customer context from your API key. You don't need to specify a customer ID in endpoints—the API automatically determines your customer from the authenticated API key.

Endpoint Reference

Core Resources

Account Management

Usage & Billing

Observability

Automation

Request Format

All POST, PUT, and PATCH requests must include:

Content-Type: application/json

Request bodies should be valid JSON:

curl -X POST https://api.dnscale.eu/v1/zones \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com",
    "type": "primary"
  }'

Response Format

All responses use a consistent envelope:

Success Response

{
  "status": "success",
  "data": {
    "id": "zone_123",
    "name": "example.com",
    "type": "primary"
  }
}

Collection Response

{
  "status": "success",
  "data": {
    "items": [...],
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Error Response

{
  "status": "error",
  "error": {
    "code": "validation_failed",
    "message": "Record type is required",
    "details": {
      "type": "This field is required"
    }
  }
}

Pagination

Collection endpoints accept limit and offset query parameters:

GET /v1/zones?limit=20&offset=0

Rate Limiting

The API enforces rate limits to ensure fair usage:

• Standard endpoints: 100 requests per minute
• Authentication endpoints: 10 requests per 5 minutes
• Email-sending endpoints: 3 requests per hour

When rate limited, you'll receive a 429 Too Many Requests response.

HTTP Status Codes

SDKs and Tools

The official DNScale TypeScript SDK is published on npm as @dnscale/dnscale. Version 1.0.0 supports TypeScript and JavaScript on Node.js 20.19 and newer, using ES modules, with typed zone and record helpers, async pagination, cancellation, and structured errors.

npm install @dnscale/dnscale@1.0.0

Set DNSCALE_API_KEY in your server environment. See the TypeScript and Node.js guide for complete examples, or browse the source on GitHub. The typed client at dns.api covers the wider public API contract.

The official DNScale Python SDK is available for Python 3.10 and newer. It includes typed zone and record helpers, pagination iterators, synchronous and asynchronous calls, and generated clients for the wider API contract.

python -m pip install dnscale

Set DNSCALE_API_KEY to a key with zones:read permission, then list the zones it can access:

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

See the Python SDK guide for authentication, zone and record examples, async calls, and error handling. The package is on PyPI and the source is on GitHub.

The official DNScale Go SDK supports Go 1.25 and newer, with typed zone and record helpers, pagination iterators, context deadlines, and structured errors.

go get github.com/dnscaleou/dnscale-go

See the Go SDK guide for complete examples, or browse the source on GitHub. The generated client at dns.API covers the wider public API contract.

All three SDKs use the same API permissions and limits. Automatic retries are limited to safe reads; changes are never automatically retried. Browse the SDKs learning section for SDK tutorials.

The REST API also works with:

• curl - Command-line examples throughout this documentation
• Postman - Import our OpenAPI spec
• Terraform - Use our DNScale Terraform provider for infrastructure as code
• DNSControl - Use the DNScale provider for DNS as code
• Ansible - Use the uri module for DNS automation