Manage DNS records

A DNS record tells the internet where a name should point — for example, that www.example.com should serve from a particular host. Once you have onboarded a domain so Comwit Cloud manages its DNS (see Bring your own domain), you can manage that domain’s records with the comwit CLI or the platform API.

Note

Record management only unlocks after your domain reaches the managed state. If delegation is still pending — or a previously managed domain stops delegating — create and update are locked. Delete always works, so you are never trapped. See Bring your own domain for how delegation is confirmed.

Supported record types

When you create a record you choose its type. Comwit Cloud supports:

Type	What it does
A	Points a name at an IPv4 address.
AAAA	Points a name at an IPv6 address.
CNAME	Aliases one name to another name.
TXT	Stores arbitrary text (verification, SPF, etc.).
MX	Routes mail for the domain.
A_ALIAS	An apex alias — lets the bare/root domain (e.g. example.com) point at a target the way a CNAME would, which a plain A record at the apex cannot.

List records

This shows every record in the domain’s zone, including ones Comwit wrote for you.

comwit CLI

comwit domains records list --project <project-id> --domain example.com

API

GET /v1/projects/{projectId}/domains/{domain}/records

What a record looks like

Each record carries an id, its name, type, TTL, one or more values, and ownership metadata:

{ "record": {
    "id": "dnsrec_...",
    "name": "www.example.com",
    "type": "CNAME",
    "ttl": 300,
    "values": ["target.example.net"],
    "owner": "user",
    "status": "in_sync"
} }

Field	Meaning
id	Stable id (dnsrec_...) you pass to update/delete.
name	The DNS name this record applies to.
type	One of the supported types above.
ttl	Time-to-live in seconds.
values	The record’s value(s) — a list, because some types (like MX) carry several.
owner	Who controls the record — see below.
status	Sync state of the record, e.g. in_sync.
last_error	A sanitized failure message, present only on failed records.

Record ownership: yours vs. Comwit’s

Every record has an owner:

• owner: "user" — records you created and manage. You can freely update or delete these.
• owner: "platform_app" — records Comwit wrote for you when you attached an app hostname using Automatic DNS (these also carry owner_resource_type: "runtime_app"). See Connect a domain to an app.

Caution

Do not try to overwrite a platform_app-owned record. Comwit owns those records for an app hostname, and conflicting user writes are rejected. If one of these records fails, its last_error field holds a sanitized message explaining why.

Create a record

comwit CLI

comwit domains records create \
  --project <project-id> \
  --domain example.com \
  --name www \
  --type CNAME \
  --value target.example.net \
  --ttl 300

API

POST /v1/projects/{projectId}/domains/{domain}/records

Tip

You can pass --value more than once for record types that hold multiple values (such as MX).

Update a record

Updating is partial: any field you leave out is loaded from the existing record. Concretely, if you omit --name, --type, or --ttl, the current value is kept. Supplying one or more --value flags replaces the record’s values.

comwit CLI

comwit domains records update \
  --project <project-id> \
  --domain example.com \
  --record <record-id> \
  --value target2.example.net \
  --ttl 300

API

PUT /v1/projects/{projectId}/domains/{domain}/records/{recordId}

Delete a record

comwit CLI

comwit domains records delete \
  --project <project-id> \
  --domain example.com \
  --record <record-id>

API

DELETE /v1/projects/{projectId}/domains/{domain}/records/{recordId}

Note

Deletion is retry-safe. If the record is already gone on the DNS provider side, Comwit treats that as clean and finishes the local cleanup — so re-running a delete that already succeeded is harmless.

Required scopes

When you call these routes with a cwt_ API token, the token must carry the right scope:

• domain:read — for list / read.
• domain:write — for create, update, and delete.

See Authentication for how token scopes work.

Related

• Bring your own domain — onboard and delegate a domain first.
• Connect a domain to an app — attach an app hostname with Automatic DNS.
• Domains overview — how domains fit together in Comwit Cloud.
• CLI reference — full command surface.