Custom domains

Every /v1 route for custom domains. 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.

Detach a custom domain

DELETE /v1/custom-domains/{domainId}

A redeploy drops the route, so the domain stops serving.

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Returns

204 with no body.

bash

curl -X DELETE "https://api.naijacloud.com/v1/custom-domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

Re-check a custom domain's DNS now

POST /v1/custom-domains/{domainId}/verify

Key scopes: WRITE and PLATFORM_API.

Path parameters

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

Returns

200 with V1CustomDomain.

bash

curl -X POST "https://api.naijacloud.com/v1/custom-domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $NC_API_KEY"

List a service's custom domains, oldest first

GET /v1/services/{serviceId}/custom-domains

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service'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: V1CustomDomain[], nextCursor }, where each item is V1CustomDomain.

bash

curl "https://api.naijacloud.com/v1/services/$SERVICE_ID/custom-domains" \
  -H "Authorization: Bearer $NC_API_KEY"

Attach a custom domain to a web service

POST /v1/services/{serviceId}/custom-domains

Create the records in dnsTarget at your DNS provider, then verify. The route and certificate apply on a redeploy that starts automatically.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service'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. `www.example.com`

Returns

201 with V1CustomDomain.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/custom-domains" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"domain":"www.example.com"}'

Types

V1CustomDomain

Field	Type	Notes
`id`	`string (uuid)`
`serviceId`	`string (uuid)`
`domain`	`string`	e.g. `www.example.com`
`status`	`PENDING`, `ACTIVE`
`lastCheck`	`string`, or `null`	What the last DNS check found.
`dnsTarget`	`V1DnsTarget`
`verifiedAt`	`string (date-time)`, or `null`
`createdAt`	`string (date-time)`

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`

V1DnsTarget

Field	Type	Notes
`cname`	`string`	CNAME target for a subdomain.
`aRecord`	`string`, or `null`	A-record address, when an apex domain cannot use a CNAME.
`isApex`	`boolean`
`records`	array of `V1DnsRecord`	Records to create.
`conflicts`	array of `V1DnsRecord`	Existing records that block verification; remove them.