---
title: Reverse Zones Reference
path: reference/reverse-zones
status: published
---

# Reverse Zones Reference

Endpoints for IPv4 and IPv6 reverse zones and their PTR records. For the conceptual model, see [Reverse Zones](../tutorials/reverse-zones.md).

**Base path:** `/api/v1/reverse-zones/`

## GET /api/v1/reverse-zones/

List reverse zones in the current tenant.

**Query parameters:**

| Param | Type | Notes |
|-------|------|-------|
| `page`, `page_size` | integer | Standard pagination |
| `search` | string | Substring match on name or CIDR |

**Response:** Same shape as `GET /api/v1/domains/`, filtered to `reverse_ipv4` and `reverse_ipv6` types.

## POST /api/v1/reverse-zones/preview

Preview the zone that would be created from a CIDR without making changes.

**Request:**

```json
{"cidr": "192.0.2.0/24"}
```

**Response:**

```json
{
  "zone_name": "2.0.192.in-addr.arpa",
  "start_ip": "192.0.2.0",
  "end_ip": "192.0.2.255",
  "ip_count": 256,
  "domain_type": "reverse_ipv4"
}
```

## POST /api/v1/reverse-zones/

Create a reverse zone from a CIDR.

**Request:**

| Field | Type | Required |
|-------|------|---------|
| `cidr` | string | Yes |
| `default_ttl` | integer | No |
| `description` | string | No |

**Response:** `DomainDetailResponse` for the new zone (status `pending_validation`).

## GET /api/v1/reverse-zones/{domain_id}/ptr

List PTR records in a reverse zone.

**Query parameters:**

| Param | Type | Notes |
|-------|------|-------|
| `page`, `page_size` | integer | |
| `search` | string | Substring match on IP or hostname |

**Response:**

```json
{
  "data": [
    {
      "id": "r_abc123",
      "ip": "192.0.2.10",
      "hostname": "host-10.example.com.",
      "ttl": 3600
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 50
}
```

## POST /api/v1/reverse-zones/{domain_id}/ptr

Create a PTR record.

**Request:**

| Field | Type | Required |
|-------|------|---------|
| `ip` | string | Yes (must be within the zone's CIDR) |
| `hostname` | string | Yes (FQDN, trailing dot recommended) |
| `ttl` | integer | No |

**Response:** Created PTR record.

## POST /api/v1/reverse-zones/{domain_id}/ptr/bulk

Create multiple PTR records atomically.

**Request:**

```json
{
  "records": [
    {"ip": "192.0.2.10", "hostname": "host-10.example.com."},
    {"ip": "192.0.2.11", "hostname": "host-11.example.com."}
  ]
}
```

**Response:**

```json
{
  "created": [...],
  "errors": [],
  "total_created": 2,
  "total_errors": 0
}
```

## DELETE /api/v1/reverse-zones/{domain_id}/ptr/{ip}

Delete a PTR by IP address (URL-encoded if IPv6).

**Response:** `204 No Content`.

## GET /api/v1/reverse-zones/lookup/{ip}

Global lookup — find the PTR for an IP across all reverse zones in the tenant. Useful when you don't know which zone the IP belongs to.

**Response:**

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

Returns `404` if no PTR exists for the IP.

## Supported CIDR sizes

**IPv4:** `/8`, `/16`, `/24` produce standard `in-addr.arpa` zones. Prefixes `/25`–`/32` use RFC 2317 classless delegation with hyphenated zone names.

**IPv6:** Prefixes that are multiples of 4 (`/4`, `/8`, ..., `/124`) produce standard `ip6.arpa` zones.

## Error codes

| Status | Meaning |
|--------|---------|
| `400` | Invalid CIDR, unsupported prefix length, IP outside zone CIDR |
| `403` | Caller lacks permission |
| `404` | Zone or PTR not found |
| `409` | PTR already exists for this IP |

## Related

- [Reverse Zones guide](../tutorials/reverse-zones.md) — conceptual walkthrough.
- [Domains reference](./domains.md) — generic zone endpoints (also work on reverse zones).
- [Records reference](./records.md) — generic record endpoints for non-PTR records on reverse zones.