---
title: "Set the hostname IP"
method: PUT
path: "/v1/hostnames/{id}"
tags: ["hostnames"]
---

# Set the hostname IP

`PUT /v1/hostnames/{id}`

## Request

- Base URL: `https://dnsmint.com/api`
- URL: `https://dnsmint.com/api/v1/hostnames/{id}`
- Auth: HTTP bearer

Puts an IP on the hostname. If the address is unchanged, DNS is not rewritten. If it changed, the record is replaced and the name comes back live. Request bodies are capped at 4KB. A hostname keeps the address class it was minted with. Repointing within a class is free, including between A and AAAA; crossing from public to private or private to public returns 409. This blocks DNS rebinding, where one origin is public first, to deliver a payload under a trusted certificate, and private second, to read a response from inside the visitor's network. Release the hostname and mint a new one for the other class.

Send `target` instead of `ip` to follow a platform endpoint that publishes no address of its own. We resolve it and serve A or AAAA, so the hostname keeps its certificates, its CAA and every child record.

## Request body

- RegisterIpRequest: Exactly one of `ip` or `target`. Setting `ip` on a hostname that follows a target takes it off that target.
  - `ip` string: An IPv4 or IPv6 address, public or private. Private and reserved ranges are accepted on every plan. A hostname keeps the address class it was minted with. Repointing within a class is free, including between A and AAAA; crossing from public to private or private to public returns 409. This blocks DNS rebinding, where one origin is public first, to deliver a payload under a trusted certificate, and private second, to read a response from inside the visitor's network. Release the hostname and mint a new one for the other class.
  - `target` string: A platform endpoint to follow instead of an address. Send this or `ip`, never both. We resolve it and publish ordinary A and AAAA records, refreshed within the target's own TTL, so the name never carries a CNAME and every record you set on the hostname keeps working. The hostname keeps the address class it was minted with, and that is re-checked every time we refresh rather than only when you set it: a target that starts answering with a private address is refused and the hostname stays on its last public one. Setting `ip` takes the hostname back off its target.

## Response `200`

The updated hostname.

- HostView: A hostname. Where it points is deliberately not here: `ip`, `record_type` and the target are either something you just sent or something DNS answers authoritatively, and a second copy in this body can only disagree with it. Ask /v1/hostnames/{id}/diagnose for where it points and what we observed, with the time we observed it.
  - `id` string, required: Opaque identifier used in the /v1/hostnames/{id} paths.
  - `hostname` string, required: The fully qualified hostname: an opaque subdomain on a domain assigned to your account.
  - `status` 'pending' | 'live' | 'released' | 'suspended' | 'terminated', required: pending: registered, not yet confirmed on the nameservers. live: the record is served, and it stays so until you release it. released: you released it; writes return 409 and the subdomain can be minted again as a new hostname. suspended: held while an abuse report is reviewed; it stops resolving and writes return 403, but nothing is lost if the report is not upheld. terminated: an abuse report was upheld, not reversible. New registrations may briefly return pending; poll GET until live.
  - `certificate` 'self' | 'csr' | 'managed', required: Who holds the private key. self: you, and you run the ACME client. csr: you hold the key and we run the protocol around your signed request. managed: we generate the key, obtain and renew the certificate, and keep a copy for you to fetch.
  - `created_at` string, date-time, required: When the hostname was registered.

## Other responses

- `400`: Invalid JSON, missing both "ip" and "target" or sending both, syntactically invalid IP address, or body over 4KB.
- `401`: The Authorization header is missing, malformed, or the key is unknown or revoked.
- `403`: The hostname is suspended pending an abuse review, or the API key does not carry the scope this call needs, or its grant does not reach this hostname.
- `404`: No hostname with this id belongs to the authenticated account.
- `409`: Either the hostname was released or terminated, neither of which can be updated, or the new address is a different class from the one the hostname was minted with: a public hostname cannot become private, or the reverse.
- `429`: More than 60 updates in a minute in this team.
- `500`: Unexpected server error.

---

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