---
title: Managing Records
path: tutorials/managing-records
status: published
---

# Managing Records

Create, read, update, and delete DNS records within an active zone. For bulk imports and bulk deletes, see [Bulk Operations](./bulk-operations.md).

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

## List records

```bash
curl https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

```python
resp = httpx.get(
    f"https://scaidns.scailabs.ai/api/v1/domains/{DOMAIN_ID}/records",
    headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
)
for r in resp.json()["data"]:
    print(r["name"], r["type"], r["content"])
```

```typescript
const resp = await fetch(
  `https://scaidns.scailabs.ai/api/v1/domains/${domainId}/records`,
  { headers: { "X-API-Key": process.env.SCAIDNS_API_KEY! } }
);
const { data } = await resp.json();
for (const r of data) console.log(r.name, r.type, r.content);
```

### Filters

| Param | Type | Notes |
|-------|------|-------|
| `type` | string | Filter by record type (`A`, `CNAME`, `TXT`, ...) |
| `name` | string | Substring match on record name |
| `include_system` | boolean | Include SOA and NS records (default: false) |

## Create a record

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "www",
    "type": "A",
    "content": "192.0.2.10",
    "ttl": 300
  }'
```

```python
resp = httpx.post(
    f"https://scaidns.scailabs.ai/api/v1/domains/{DOMAIN_ID}/records",
    headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
    json={
        "name": "www",
        "type": "A",
        "content": "192.0.2.10",
        "ttl": 300,
    },
)
record = resp.json()
print(record["id"])
```

```typescript
const resp = await fetch(
  `https://scaidns.scailabs.ai/api/v1/domains/${domainId}/records`,
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.SCAIDNS_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "www",
      type: "A",
      content: "192.0.2.10",
      ttl: 300,
    }),
  },
);
const record = await resp.json();
```

### Request body

| Field | Type | Required | Notes |
|-------|------|---------|-------|
| `name` | string | Yes | Relative name (`www`) or `@` for apex. FQDN accepted |
| `type` | string | Yes | Uppercase DNS type (`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, `PTR`, `CAA`, `SSHFP`, `TLSA`, `DNAME`, `ALIAS`, `DS`) |
| `content` | string | Yes | Record data in zone-file format |
| `ttl` | integer | No | Seconds; defaults to zone's `default_ttl` |
| `disabled` | boolean | No | Store but don't serve |

### Content formatting by type

| Type | Content |
|------|---------|
| `A` | `192.0.2.1` |
| `AAAA` | `2001:db8::1` |
| `CNAME` | `target.example.com.` (trailing dot recommended) |
| `MX` | `10 mail.example.com.` (priority + target) |
| `NS` | `ns1.example.com.` |
| `TXT` | `"v=spf1 -all"` — quotes required for multi-word content |
| `SRV` | `10 5 5060 sipserver.example.com.` (priority weight port target) |
| `CAA` | `0 issue "letsencrypt.org"` (flags tag value) |
| `PTR` | `host.example.com.` |

## Get a record

```bash
curl https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records/$RECORD_ID \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

## Update a record

Only `content`, `ttl`, and `disabled` are editable. To change the name or type, delete and recreate.

```bash
curl -X PATCH https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records/$RECORD_ID \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "192.0.2.20", "ttl": 600}'
```

## Delete a record

```bash
curl -X DELETE https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records/$RECORD_ID \
  -H "X-API-Key: $SCAIDNS_API_KEY"
```

Returns `204 No Content`. Deletion is immediate and not recoverable — there's no soft delete for records.

## Search records

For more flexible search across all your records (within a domain):

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records/search \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mail", "limit": 50}'
```

Matches against both name and content.

## Disabling vs deleting

A **disabled** record is stored but excluded from DNS responses:

```bash
curl -X PATCH https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records/$RECORD_ID \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'
```

Use when you want to temporarily remove an answer without losing the content. Re-enable later by setting `disabled: false`.

## Common patterns

### Mail setup (MX + SPF + DMARC)

```python
records = [
    {"name": "@",        "type": "MX",  "content": "10 mail.example.com.", "ttl": 3600},
    {"name": "@",        "type": "TXT", "content": '"v=spf1 mx -all"', "ttl": 3600},
    {"name": "_dmarc",   "type": "TXT", "content": '"v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com"', "ttl": 3600},
]
httpx.post(
    f"https://scaidns.scailabs.ai/api/v1/domains/{DOMAIN_ID}/records/bulk",
    headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
    json={"records": records},
)
```

For DKIM and other standard mail records, consider using a [template](./templates.md).

### Apex ALIAS (avoiding CNAME-at-apex)

RFC 1034 forbids CNAME at the zone apex. If you need the apex to follow a hostname, use an `ALIAS` record:

```bash
curl -X POST https://scaidns.scailabs.ai/api/v1/domains/$DOMAIN_ID/records \
  -H "X-API-Key: $SCAIDNS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "@", "type": "ALIAS", "content": "target.example.com.", "ttl": 300}'
```

ALIAS is a PowerDNS feature — resolved server-side to the target's A/AAAA at query time.

### Round-robin

Create multiple records with the same name and type:

```python
for ip in ["192.0.2.10", "192.0.2.11", "192.0.2.12"]:
    httpx.post(
        f"https://scaidns.scailabs.ai/api/v1/domains/{DOMAIN_ID}/records",
        headers={"X-API-Key": os.environ["SCAIDNS_API_KEY"]},
        json={"name": "www", "type": "A", "content": ip, "ttl": 60},
    )
```

PowerDNS returns all three in an RRset; resolvers shuffle them.

## What's next

- [Bulk Operations](./bulk-operations.md) — import many records at once.
- [Templates](./templates.md) — reusable record sets.
- [Records reference](../reference/records.md) — endpoint-level details.