Records Reference
DNS record endpoints. All are nested under a specific domain ID. For the conceptual model, see Zones and Records. For task walkthroughs, see Managing Records.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
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. Every field is optional; omitted fields keep their current value.
Request:
| Field | Type | Notes |
|---|---|---|
name |
string | Renames the record. Relative to the zone, or an FQDN. |
record_type |
string | Retypes the record. content must be valid for the new type. |
content |
string | |
ttl |
integer | |
disabled |
boolean |
Response: Updated record.
Renaming and retyping#
DNS has no rename primitive — a record's name and type identify which rrset it
belongs to. Supplying name or record_type therefore moves the record:
it is removed from the old rrset and inserted into the new one. Both changes go
out in a single PowerDNS patch, so the move is atomic; a failure cannot leave
the record deleted without being recreated.
Consequences worth knowing:
- The record id changes. Ids are derived from name + type + content, so any
move returns a new
id. Use the id from the response for subsequent calls. - Moving onto an existing name merges. If the target name/type already holds records, the moved value is appended to that rrset; existing values are kept.
- Siblings stay put. Moving one value out of a multi-value rrset leaves the others where they were.
Refused, with the zone left untouched:
| Condition | Status |
|---|---|
| An identical record already exists at the target | 409 |
| The target name holds a CNAME (or the move would add a CNAME alongside other data) | 409 |
content is not valid for the new record_type |
422 |
The record is an SOA, or the target type is SOA |
422 |
The record is an apex NS |
422 |
1 2 3 4 5 | |
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:
1 2 3 4 5 6 7 | |
Response:
1 2 3 4 5 6 | |
See Bulk Operations for semantics.
POST /api/v1/domains/{domain_id}/records/bulk-delete#
Bulk delete records by ID.
Request:
1 | |
Response:
1 | |
POST /api/v1/domains/{domain_id}/records/search#
Search records by query string. Matches against name and content.
Request:
1 | |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | |
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 — guide.
- Bulk Operations — bulk semantics.
- Import and Export — whole-zone operations.