---
title: Records Reference
path: reference/records
status: published
---

# Records Reference

DNS record endpoints. All are nested under a specific domain ID. For the conceptual model, see [Zones and Records](../concepts/zones-and-records.md). For task walkthroughs, see [Managing Records](../tutorials/managing-records.md).

**Base path:** `/api/v1/domains/{domain_id}/records`
**Required permission:** `records:read`, `records:create`, `records:update`, `records:delete`

## GET /api/v1/domains/{domain_id}/records

List records for a zone.

**Query parameters:**

| Param | Type | Notes |
|-------|------|-------|
| `type` | string | Filter by record type |
| `name` | string | Substring match |
| `include_system` | boolean | Include SOA and NS (default false) |

**Response:**

```json
{
  "data": [
    {
      "id": "r_abc123",
      "name": "www.example.com",
      "display_name": "www",
      "type": "A",
      "content": "192.0.2.10",
      "ttl": 300,
      "disabled": false,
      "domain_id": "d_xyz789",
      "created_at": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 17,
  "domain_id": "d_xyz789",
  "domain_name": "example.com"
}
```

## POST /api/v1/domains/{domain_id}/records

Create a record.

**Request:**

| Field | Type | Required | Notes |
|-------|------|---------|-------|
| `name` | string | Yes | `@` for apex, or relative hostname |
| `type` | string | Yes | Uppercase DNS type |
| `content` | string | Yes | Zone-file formatted content |
| `ttl` | integer | No | Defaults to zone's `default_ttl` |
| `disabled` | boolean | No | Default false |

**Response:** Created record.

## GET /api/v1/domains/{domain_id}/records/{record_id}

Get a specific record by ID.

## PATCH /api/v1/domains/{domain_id}/records/{record_id}

Update a record. Only `content`, `ttl`, and `disabled` are editable.

**Request:**

| Field | Type |
|-------|------|
| `content` | string |
| `ttl` | integer |
| `disabled` | boolean |

**Response:** Updated record.

## DELETE /api/v1/domains/{domain_id}/records/{record_id}

Delete a record. Immediate and not recoverable.

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

## POST /api/v1/domains/{domain_id}/records/bulk

Bulk create records.

**Request:**

```json
{
  "records": [
    {"name": "app1", "type": "A", "content": "192.0.2.10", "ttl": 300},
    {"name": "app2", "type": "A", "content": "192.0.2.11", "ttl": 300}
  ],
  "continue_on_error": false
}
```

**Response:**

```json
{
  "created": [...],
  "errors": [{"index": 1, "name": "app2", "error": "..."}],
  "total_created": 1,
  "total_errors": 1
}
```

See [Bulk Operations](../tutorials/bulk-operations.md) for semantics.

## POST /api/v1/domains/{domain_id}/records/bulk-delete

Bulk delete records by ID.

**Request:**

```json
{"record_ids": ["r_abc", "r_def"]}
```

**Response:**

```json
{"deleted": 2, "errors": [], "total_deleted": 2, "total_errors": 0}
```

## POST /api/v1/domains/{domain_id}/records/search

Search records by query string. Matches against name and content.

**Request:**

```json
{"query": "mail", "limit": 50}
```

**Response:** Same as list response shape.

## GET /api/v1/domains/types

List supported DNS record types with descriptions and example content. Public (no auth required).

**Response:**

```json
{
  "types": [
    {"type": "A", "description": "IPv4 address", "example": "192.0.2.1"},
    {"type": "AAAA", "description": "IPv6 address", "example": "2001:db8::1"},
    {"type": "CNAME", "description": "Canonical name", "example": "target.example.com."},
    {"type": "MX", "description": "Mail exchanger", "example": "10 mail.example.com."},
    {"type": "NS", "description": "Nameserver", "example": "ns1.example.com."},
    {"type": "TXT", "description": "Text", "example": "\"v=spf1 -all\""},
    {"type": "SRV", "description": "Service locator", "example": "10 5 5060 sipserver.example.com."},
    {"type": "PTR", "description": "Reverse pointer", "example": "host.example.com."},
    {"type": "CAA", "description": "CA authorization", "example": "0 issue \"letsencrypt.org\""},
    {"type": "SSHFP", "description": "SSH fingerprint", "example": "1 1 <hex>"},
    {"type": "TLSA", "description": "DANE TLS binding", "example": "3 1 1 <hex>"},
    {"type": "DNAME", "description": "Subtree alias", "example": "target.example.com."},
    {"type": "ALIAS", "description": "Apex-compatible alias", "example": "target.example.com."}
  ]
}
```

## Schemas

### Record

| Field | Type |
|-------|------|
| `id` | string (UUID) |
| `name` | string — FQDN |
| `display_name` | string — relative to zone |
| `type` | string |
| `content` | string |
| `ttl` | integer |
| `disabled` | boolean |
| `domain_id` | string (UUID) |
| `created_at` | ISO 8601 timestamp |

## Error codes

| Status | Meaning |
|--------|---------|
| `400` | Invalid content for the record type |
| `403` | Caller lacks `records:*` permission on this domain |
| `404` | Domain or record not found |
| `409` | Duplicate record, or type conflicts (CNAME + A, DNAME coexistence) |
| `422` | Schema validation failed |

## Related

- [Managing Records](../tutorials/managing-records.md) — guide.
- [Bulk Operations](../tutorials/bulk-operations.md) — bulk semantics.
- [Import and Export](../tutorials/import-export.md) — whole-zone operations.