---
title: "Add, change or delete a DNS record"
method: POST
path: "/domains/{id}/dns-records"
tags: ["Domains"]
---

# Add, change or delete a DNS record

`POST /domains/{id}/dns-records`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/domains/{id}/dns-records`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `sites:write`)

Without record_id a new record (a new A, AAAA or CNAME replaces the A, AAAA or CNAME on that name); with record_id that record is replaced; with delete true it is deleted. The records that serve the site cannot be changed here. On an active domain, a change that replaces or deletes a live record returns 409 confirmation_required with preflight (what changes, what is live there now, mail_affected) and nothing changes; call again with confirm_overwrite true once the user agreed. Every change keeps the previous state for POST /domains/{id}/dns-records/undo.

## Path parameters

- `id` string, uuid, required

## Request body

- DnsRecordInput
  - `record_id` string: Optional. The id from list_dns_records of the record to change or delete. Without it, a new record is added.
  - `type` 'A' | 'AAAA' | 'CNAME' | 'MX' | 'TXT' | 'SRV' | 'CAA' | 'NS', required: The record type.
  - `name` string, required: The name: @ for the domain itself, or a subdomain like www, mail or _dmarc.
  - `content` string: The value: an IP address, a hostname, or the text of a TXT record. For SRV: 'priority weight port target'. For CAA: 'flags tag "value"'.
  - `ttl` integer: Seconds; 1 means automatic.
  - `priority` integer: For MX: the priority (lower is preferred).
  - `proxied` boolean: For A, AAAA and CNAME: through the CDN (true) or DNS only (false, default).
  - `delete` boolean: true deletes the record with record_id.
  - `confirm_overwrite` boolean: Optional, default false. A change that replaces or deletes a record that is live now (on an active domain) is refused first with a preflight: what changes, what is live there now, and whether mail is affected. Show it to the user; only after they agree, call again with true. undo_dns_change reverses it for 30 days.

## Response `200`

The record (or deleted: true), what it replaced, and how to undo it.

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `404`: Not Found: not_found.
- `409`: Conflict: conflict, confirmation_required.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)