Versioning

Our public REST API is currently versioned at v1. All production endpoints live under /v1.

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

Resource	Endpoints	Description
Zones	`/v1/zones`	Create and manage DNS zones
Records	`/v1/zones/{zone_id}/records`	Manage DNS records within zones
DNSSEC	`/v1/zones/{zone_id}/dnssec`	DNSSEC key management

Account Management

Resource	Endpoints	Description
Users	`/v1/users`	Manage team members
API Keys	`/v1/users/{user_id}/apikeys`	Create and manage API keys
Invitations	`/v1/invitations-admin`	Invite team members

Usage & Billing

Resource	Endpoints	Description
Usage	`/v1/usage`	Query usage statistics
Billing	`/v1/billing`	Billing summaries and history

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

Parameter	Default	Maximum	Description
`limit`	10	100	Number of items per page
`offset`	0	-	Number of items to skip

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

Code	Description
`200`	Success
`201`	Created
`202`	Accepted (async operation started)
`400`	Bad Request (validation error)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (insufficient permissions)
`404`	Not Found
`429`	Too Many Requests (rate limited)
`500`	Internal Server Error

SDKs and Tools

While we don't provide official SDKs yet, the REST API works well 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

API Overview