Manage a domain

After registering or transferring a domain, you can update its configuration at any time using the OpusDNS API. This guide covers the most common management tasks.

Update nameservers

Replace the nameservers on a domain with PATCH /v1/domains/{domain_reference}. Pass the full set of nameservers you want — the existing list is replaced entirely. See Using OpusDNS Nameservers for the OpusDNS nameserver hostnames.

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "nameservers": [
      { "hostname": "ns1.newprovider.net" },
      { "hostname": "ns2.newprovider.net" }
    ]
  }'

Update contacts

Change any contact role by providing the contact ID for that role:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contacts": {
      "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2",
      "admin": "contact_01j7abc123def456ghi789jkl"
    }
  }'

You only need to include the roles you want to change. Roles you omit remain unchanged.

Change renewal mode

Set renewal_mode to control what happens when the domain approaches its expiry date:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "renewal_mode": "expire"
  }'

Manage domain statuses

Domain statuses control what operations are allowed. You can manage them in two ways:

Option 1: Declarative replacement

Set statuses to replace the entire status list. This is useful when you know the exact set of statuses you want:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "statuses": ["clientTransferProhibited"]
  }'

Option 2: Delta changes

Use status_changes to add or remove individual statuses without affecting others:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status_changes": {
      "add": ["clientTransferProhibited"],
      "remove": ["clientDeleteProhibited"]
    }
  }'

Transfer lock

The transfer_lock field in the domain response is derived from the clientTransferProhibited status. To lock or unlock a domain for transfers, add or remove that status.

Blocking statuses

Certain statuses prevent domain updates entirely. If any of these are active, you must remove them before making other changes:

• clientUpdateProhibited
• serverUpdateProhibited
• pendingTransfer
• pendingRestore
• pendingDelete
• redemptionPeriod

Rotate auth code

Generate a new authorization code for a domain:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --request PATCH \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "auth_code": "NEW-AUTH-CODE-VALUE"
  }'

The auth code is required when transferring the domain to another registrar.

Retrieve domain details

Fetch the current state of a domain by name or ID:

curl "$OPUSDNS_API_BASE/v1/domains/example.com" \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

The response includes all domain details: nameservers, contacts, statuses, registration and expiry dates, renewal mode, and more.

Related API Reference

• PATCH /v1/domains/{domain_reference}
• GET /v1/domains/{domain_reference}