Domains & DNS

Every /v1 route for domains & dns. This page is generated from the API's OpenAPI contract, so it always matches what the API accepts and returns.

Authentication, pagination, errors and idempotency work the same on every route. They are described once, in the API overview.

Replace a record

PATCH /v1/dns-records/{recordId}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`recordId`	`string`	yes	The record's id.

Body

Field	Type	Required	Notes
`name`	`string`	yes	"@" for the zone apex, or a label.
`type`	`string`	yes	A, AAAA, CNAME, MX, TXT, …
`content`	`string`	yes
`ttl`	`integer`	no
`priority`	`integer`	no

Returns

200 with V1DnsRecord.

bash

curl -X PATCH "https://api.naijacloud.com/v1/dns-records/$RECORD_ID" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","type":"…","content":"…"}'

Delete a record

DELETE /v1/dns-records/{recordId}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`recordId`	`string`	yes	The record's id.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/dns-records/$RECORD_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Stop hosting a zone, with all its records

DELETE /v1/dns-zones/{zoneId}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`zoneId`	`string`	yes	The zone's id.

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/dns-zones/$ZONE_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Turn auto-renew on or off, or change the nameservers

PATCH /v1/registered-domains/{domainId}

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`domainId`	`string`	yes	The domain's id.

Body

Field	Type	Required	Notes
`autoRenew`	`boolean`	no
`nameserverMode`	`CUSTOM`, `NC`	no	Use our nameservers, or your own (then `nameservers`).
`nameservers`	array of `string`	no

Returns

200 with V1RegisteredDomain.

bash

curl -X PATCH "https://api.naijacloud.com/v1/registered-domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoRenew":true,"nameserverMode":"CUSTOM"}'

The zone as a BIND zone file

GET /v1/dns-zones/{zoneId}/export

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`zoneId`	`string`	yes	The zone's id.

Returns

200 with no body.

bash

curl "https://api.naijacloud.com/v1/dns-zones/$ZONE_ID/export" \
  -H "Authorization: Bearer $NC_API_KEY"

A zone's records

GET /v1/dns-zones/{zoneId}/records

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`zoneId`	`string`	yes	The zone's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1DnsRecord[], nextCursor }, where each item is V1DnsRecord.

bash

curl "https://api.naijacloud.com/v1/dns-zones/$ZONE_ID/records" \
  -H "Authorization: Bearer $NC_API_KEY"

Add a record; published straight away

POST /v1/dns-zones/{zoneId}/records

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`zoneId`	`string`	yes	The zone's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`name`	`string`	yes	"@" for the zone apex, or a label.
`type`	`string`	yes	A, AAAA, CNAME, MX, TXT, …
`content`	`string`	yes
`ttl`	`integer`	no
`priority`	`integer`	no

Returns

201 with V1DnsRecord.

bash

curl -X POST "https://api.naijacloud.com/v1/dns-zones/$ZONE_ID/records" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","type":"…","content":"…"}'

Check ownership now and publish when proven

POST /v1/dns-zones/{zoneId}/verify

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`zoneId`	`string`	yes	The zone's id.

Returns

200 with V1DnsZone.

bash

curl -X POST "https://api.naijacloud.com/v1/dns-zones/$ZONE_ID/verify" \
  -H "Authorization: Bearer $NC_API_KEY"

What renewing would cost, and the new expiry

GET /v1/registered-domains/{domainId}/renewal-quote

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`domainId`	`string`	yes	The domain's id.

Query parameters

Name	Type	Required	Notes
`years`	`integer`	no

Returns

200 with V1DomainRenewalQuote.

bash

curl "https://api.naijacloud.com/v1/registered-domains/$DOMAIN_ID/renewal-quote" \
  -H "Authorization: Bearer $NC_API_KEY"

Start renewing a domain; returns a checkout link

POST /v1/registered-domains/{domainId}/renewals

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`domainId`	`string`	yes	The domain's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`years`	`number`	no

Returns

201 with V1DomainCheckout.

bash

curl -X POST "https://api.naijacloud.com/v1/registered-domains/$DOMAIN_ID/renewals" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"years":1}'

A workspace's DNS zones

GET /v1/workspaces/{workspaceId}/dns-zones

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1DnsZone[], nextCursor }, where each item is V1DnsZone.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/dns-zones" \
  -H "Authorization: Bearer $NC_API_KEY"

Host a domain’s DNS with us

POST /v1/workspaces/{workspaceId}/dns-zones

The zone stays unpublished until ownership is proven: add verificationRecord, or point the nameservers at us, then verify.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`name`	`string`	yes	e.g. `acme.ng`

Returns

201 with V1DnsZone.

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/dns-zones" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"acme.ng"}'

Whether exact names can be bought, and for how much

GET /v1/workspaces/{workspaceId}/domain-availability

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`domains`	array of `string`	yes	Up to 20 full names, e.g. domains=acme.ng&domains=acme.com

Returns

200 with a page: { data: V1DomainSearchRow[], nextCursor }, where each item is V1DomainSearchRow.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/domain-availability?domains=%E2%80%A6" \
  -H "Authorization: Bearer $NC_API_KEY"

Domain purchases and renewals, newest first

GET /v1/workspaces/{workspaceId}/domain-orders

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Returns

200 with a page: { data: V1DomainOrder[], nextCursor }, where each item is V1DomainOrder.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/domain-orders" \
  -H "Authorization: Bearer $NC_API_KEY"

Search for a domain to buy, with prices in kobo

GET /v1/workspaces/{workspaceId}/domain-search

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Query parameters

Name	Type	Required	Notes
`query`	`string`	yes

Returns

200 with V1DomainSearchResults.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/domain-search?query=acme" \
  -H "Authorization: Bearer $NC_API_KEY"

Domains this workspace owns through us

GET /v1/workspaces/{workspaceId}/registered-domains

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Returns

200 with a page: { data: V1RegisteredDomain[], nextCursor }, where each item is V1RegisteredDomain.

bash

curl "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/registered-domains" \
  -H "Authorization: Bearer $NC_API_KEY"

Start buying a domain

POST /v1/workspaces/{workspaceId}/registered-domains

Returns a checkout link; the domain is registered once it is paid. The price is our catalogue price for the term.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`workspaceId`	`string`	yes	The workspace's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Body

Field	Type	Required	Notes
`domain`	`string`	yes	e.g. `acme.com.ng`
`years`	`integer`	yes
`contact`	`object`	yes	The registrant: the same contact fields as the dashboard checkout. The price is never taken from the request.

Returns

201 with V1DomainCheckout.

bash

curl -X POST "https://api.naijacloud.com/v1/workspaces/$WORKSPACE_ID/registered-domains" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"domain":"acme.com.ng","years":1,"contact":{}}'

Types

V1DnsRecord

Field	Type	Notes
`content`	`string`
`createdAt`	`string (date-time)`
`editable`	`boolean`
`id`	`string`
`name`	`string`
`origin`	`MAIL`, `SERVICE`, `USER`
`priority`	`integer`, or `null`
`ttl`	`integer`
`type`	`A`, `AAAA`, `ALIAS`, `CAA`, `CNAME`, `MX`, `NS`, `SRV`, `TXT`
`updatedAt`	`string (date-time)`
`zoneId`	`string`

V1DnsZone

Field	Type	Notes
`createdAt`	`string (date-time)`
`id`	`string`
`lastError`	`string`, or `null`
`name`	`string`
`published`	`boolean`
`publishedAt`	`string (date-time)`, or `null`
`teamId`	`string`
`updatedAt`	`string (date-time)`
`verificationMethod`	`LEGACY`, `NS`, `PURCHASE`, `TXT`, or `null`	How ownership of the domain was proven; null while pending.
`verificationRecord`	`V1DnsZoneVerificationRecord`, or `null`	The TXT record that proves ownership while the zone is pending verification; null once ownership is proven.
`verifiedAt`	`string (date-time)`, or `null`	When ownership of the domain was proven. Null while the zone is pending verification: it is not published and its name is not yet exclusively held.

V1DnsZoneVerificationRecord

Field	Type	Notes
`host`	`string`	Record name relative to the domain, e.g. _naijacloud-verify
`name`	`string`	Fully-qualified record name, e.g. _naijacloud-verify.example.com
`type`	`string`	Always TXT.
`value`	`string`	The exact value the TXT record must hold.

V1DomainCheckout

Field	Type	Notes
`amountKobo`	`number`	What they will be charged, in kobo
`checkoutUrl`	`string`	The hosted payment page to send the customer to
`reference`	`string`	Our reference for the order; echoed back on payment

V1DomainOrder

Field	Type	Notes
`amountKobo`	`number`
`createdAt`	`string (date-time)`
`domain`	`string`
`failureReason`	`string`, or `null`
`id`	`string`
`kind`	`REGISTER`, `RENEW`
`reference`	`string`
`status`	`ABANDONED`, `FULFILLED`, `PAID`, `PENDING`, `REFUNDED`, `REFUND_DUE`
`teamId`	`string`
`updatedAt`	`string (date-time)`
`years`	`number`

V1DomainRenewalQuote

Field	Type	Notes
`amountKobo`	`number`	What the customer pays, in kobo. Firm — the checkout is created for exactly this amount.
`domain`	`string`
`expiresAt`	`string (date-time)`, or `null`	The current expiry date, or null if we hold none
`newExpiresAt`	`string (date-time)`	What the expiry becomes once paid. Extends the current date rather than restarting from today, so renewing early loses nothing.
`years`	`integer`	Years this quote covers

V1DomainSearchResults

Field	Type	Notes
`available`	array of `V1DomainSearchRow`	What they asked for and can have, cheapest first
`availableCount`	`integer`	How many rows across all groups can be bought
`query`	`string`	The bare name searched, after stripping any URL
`suggestions`	array of `V1DomainSearchRow`	Name variants they could have instead, cheapest first. Always available — a suggestion somebody else owns is not a suggestion.
`unavailable`	array of `V1DomainSearchRow`	What they cannot have, each row carrying its own reason. Returned rather than dropped: somebody who typed a .ng needs to see why.

V1DomainSearchRow

Field	Type	Notes
`available`	`boolean`	Whether this domain can be bought here, right now
`domain`	`string`
`premium`	`boolean`	Premium names are priced individually by the registry and cost far more than the standard rate
`priceKobo`	`number`, or `null`	What the customer pays, in kobo, for `years`. Firm, not an estimate — the checkout is created for exactly this amount, so the row, the payment page and the receipt agree. Null when it cannot be sold or cannot be priced right now.
`unavailableCode`	`CHECK_FAILED`, `PRICING_UNAVAILABLE`, `TAKEN`, `TLD_COMING_SOON`, `TLD_UNSUPPORTED`, or `null`	The same answer as a code. Branch on this, not on the sentence — the sentence is copy and will be reworded, and "somebody else has it" and "we cannot sell it yet" are opposite answers that look alike.
`unavailableReason`	`string`, or `null`	Why it cannot be bought, in words meant for the customer
`years`	`integer`	Years the price covers — some registries only allow one

V1RegisteredDomain

Field	Type	Notes
`autoRenew`	`boolean`
`createdAt`	`string (date-time)`
`customNameservers`	array of `string`, or `null`
`domain`	`string`
`expiresAt`	`string (date-time)`, or `null`
`id`	`string`
`lastError`	`string`, or `null`
`nameserverMode`	`CUSTOM`, `NC`
`registeredAt`	`string (date-time)`, or `null`
`registrantVerifiedAt`	`string (date-time)`, or `null`
`status`	`ACTIVE`, `DELETED`, `EXPIRING`, `FAILED`, `GRACE`, `PENDING_PAYMENT`, `REDEMPTION`, `REGISTERING`
`teamId`	`string`
`tld`	`string`
`transferLockUntil`	`string (date-time)`, or `null`
`updatedAt`	`string (date-time)`