# DNS and domains

## When to use this

A new site needs its domain to point at the server. Reads need `dns:read`, creating records needs `dns:write`.

## See what is needed

```bash
curl -s -H "Authorization: Bearer $TOKEN" $MYFORGE/sites/SITE_ID/dns
```

The answer tells you which records the site needs and where the domain's DNS is hosted. Other helpers:

- `GET /dns/zones`: domains pfcloud can manage through the team's DNS connections.
- `GET /dns/suggestions`: free subdomains you could use for a new site.

## Create the missing records

```bash
curl -s -X POST $MYFORGE/sites/SITE_ID/dns \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: dns-shop-1"
```

pfcloud adds the missing A records through the team's DNS connection (set in team settings, DNS). It never changes a record that points somewhere else. The answer lists what was created, what was skipped (pointing elsewhere) and the names you must change by hand. HTTPS follows a few minutes later.

## No DNS connection?

Create the A records at your DNS host by hand (the site's DNS answer shows the server address). pfcloud notices when the name resolves to the server.

## What can go wrong

| Problem | Fix |
| --- | --- |
| Zone not listed | Connect the DNS provider in team settings first. |
| Name skipped | It already points elsewhere. Change it yourself if that is intended. |
| Domain behind Cloudflare proxy | HTTPS uses a different method; see [HTTPS certificates](/developers/https-certificates). |