---
title: Reverse Zones
path: tutorials/reverse-zones
status: published
---

# Reverse Zones

Reverse DNS maps IP addresses to names via zones named after the reversed IP. ScaiDNS has a dedicated API that accepts CIDR input and manages PTR records by IP instead of by reversed octets.

**Base path:** `/api/v1/reverse-zones/`
**Required permission:** `domains:*` and `records:*` on the reverse zone

## Concepts

An IPv4 reverse zone's name is derived from reversing the octets of the network and appending `.in-addr.arpa`:

- `192.0.2.0/24` → `2.0.192.in-addr.arpa`
- `10.0.0.0/16` → `0.10.in-addr.arpa`
- `10.0.0.0/8` → `10.in-addr.arpa`

IPv6 reverse zones use the nibble form with `.ip6.arpa`.

ScaiDNS hides this by accepting CIDR input directly. You give it `192.0.2.0/24`, it creates `2.0.192.in-addr.arpa` and lets you add PTR records keyed by IP.

## Preview

Before creating, preview what zones will be created from a CIDR:

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/reverse-zones/preview \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cidr": "10.0.0.0/16"}'
```

```python
resp = httpx.post(
    "https://scaidns.scailabs.ai/api/v1/reverse-zones/preview",
    headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
    json={"cidr": "10.0.0.0/16"},
)
print(resp.json())
```

```typescript
const resp = await fetch(
  "https://scaidns.scailabs.ai/api/v1/reverse-zones/preview",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.SCAIDNS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ cidr: "10.0.0.0/16" }),
  },
);
console.log(await resp.json());
```

Response includes the zone name that would be created and the IP range it covers:

```json
{
  "zone_name": "0.10.in-addr.arpa",
  "start_ip": "10.0.0.0",
  "end_ip": "10.0.255.255",
  "ip_count": 65536,
  "domain_type": "reverse_ipv4"
}
```

## Create from CIDR

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/reverse-zones/ \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cidr": "192.0.2.0/24",
    "default_ttl": 3600,
    "description": "Office subnet"
  }'
```

Returns a domain record like any other — you'll get a `pending_validation` zone that you then validate through the same TXT mechanism as forward zones. See [Domain Validation](../concepts/validation.md).

Reverse zones often skip validation in internal deployments; a user with the `validation_bypass` permission can create them ready-to-use.

## Supported prefix lengths

IPv4:

| Prefix | Example | Zones created |
|--------|---------|---------------|
| `/8` | `10.0.0.0/8` | One zone: `10.in-addr.arpa` |
| `/16` | `10.0.0.0/16` | One zone: `0.10.in-addr.arpa` |
| `/24` | `192.0.2.0/24` | One zone: `2.0.192.in-addr.arpa` |
| `/25`–`/32` | `192.0.2.0/28` | Classless (RFC 2317) — creates a zone with a hyphenated name |

IPv6:

| Prefix | Zones created |
|--------|---------------|
| `/4`, `/8`, ... `/124` (multiples of 4) | Single zone |
| Other | Not yet supported |

For subnets that don't align to octet/nibble boundaries, RFC 2317 classless delegation is used automatically — the zone name includes the prefix length.

## PTR records

PTR records live inside reverse zones. ScaiDNS lets you address them by IP rather than by reversed name.

### Create a PTR

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/reverse-zones/$ZONE_ID/ptr \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.0.2.10",
    "hostname": "host-10.example.com.",
    "ttl": 3600
  }'
```

```python
resp = httpx.post(
    f"https://scaidns.scailabs.ai/api/v1/reverse-zones/{ZONE_ID}/ptr",
    headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
    json={
        "ip": "192.0.2.10",
        "hostname": "host-10.example.com.",
        "ttl": 3600,
    },
)
```

```typescript
await fetch(
  `https://scaidns.scailabs.ai/api/v1/reverse-zones/${zoneId}/ptr`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.SCAIDNS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ip: "192.0.2.10",
      hostname: "host-10.example.com.",
      ttl: 3600,
    }),
  },
);
```

ScaiDNS validates that the IP falls within the zone's CIDR, then creates the underlying PTR record.

### List PTR records

```bash
curl https://scaidns.scailabs.ai/api/v1/reverse-zones/$ZONE_ID/ptr \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

Returns a list with `ip`, `hostname`, `ttl`, and the underlying record ID.

### Delete a PTR

```bash
curl -X DELETE "https://scaidns.scailabs.ai/api/v1/reverse-zones/$ZONE_ID/ptr/192.0.2.10" \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

Delete by IP address directly — no need to look up the record ID.

### Bulk create

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/reverse-zones/$ZONE_ID/ptr/bulk \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"ip": "192.0.2.10", "hostname": "host-10.example.com."},
      {"ip": "192.0.2.11", "hostname": "host-11.example.com."},
      {"ip": "192.0.2.12", "hostname": "host-12.example.com."}
    ]
  }'
```

## Global reverse lookup

Given only an IP, find the PTR and owning zone across all of your tenant's reverse zones:

```bash
curl https://scaidns.scailabs.ai/api/v1/reverse-zones/lookup/192.0.2.10 \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

Response:

```json
{
  "ip": "192.0.2.10",
  "hostname": "host-10.example.com.",
  "zone_id": "z_abc123",
  "zone_name": "2.0.192.in-addr.arpa"
}
```

## Advanced records on reverse zones

Reverse zones occasionally need records other than PTR — notably the zone's own NS and SOA records are managed automatically, but you may want to add extra NS (for delegation) or TXT (for documentation).

Use the standard `/api/v1/domains/{domain_id}/records` endpoint on the reverse zone's domain ID. The reverse zone API is a convenience layer for PTR records; the full record API works just fine.

## What's next

- [Managing Records](./managing-records.md) — generic record management (also works on reverse zones).
- [Reverse Zones reference](../reference/reverse-zones.md) — endpoint details.