Managing Records

Create, read, update, and delete DNS records within an active zone. For bulk imports and bulk deletes, see Bulk Operations.

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.

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 — import many records at once.
Templates — reusable record sets.
Records reference — endpoint-level details.