Add a Domain

Add a domain in the specified region.

Request URL

POST {base_url}/uc-user/api/v1/domains/regions/{region}

Request parameters

Headers


Parameter	Required	Type	Description
Authorization	Yes	String	The access token used for authentication. Format: Bearer `{access_token}`.

Path parameters


Parameter	Required	Type	Description
region	Yes	String	The region code associated with the domain to create.

Body parameters


Parameter	Required	Type	Description
domain	Yes	String	The domain name in lowercase. Note: Wildcard domains (e.g. `*.itsp.com`) and IP address are not allowed. The maximum character length is 200.
certificateManagement	Yes	String	The certificate management method of the domain. Valid value: `AUTO`: The certificate is managed automatically by the platform. `CUSTOM`: The certificate is uploaded by the user.
privateKey	No	String	The private key of the custom certificate in PEM format. Note: This parameter is required when `certificateManagement` is set to `CUSTOM`.
certificate	No	String	The content of the custom certificate in PEM format. Note: This parameter is required when `certificateManagement` is set to `CUSTOM`.
autoRenewEnabled	No	Boolean	Whether to enable automatic certificate renewal. Note: This parameter is available only when `certificateManagement` is set to `AUTO`. Valid value: `true`: Enabled. `false`: Disabled.
clusterIssuerRef	No	String	The name of the ClusterIssuer. Note: You can query the ClusterIssuer name using the Preview Domain DNS Records interface.
acmeAlias	No	String	The ACME DNS-01 delegation root domain. Note: You can query the domain using the Preview Domain DNS Records interface.
dnsCheckResults	No	Array<DNS_Check_Result>	The DNS check results. Note: You can query the DNS check result using the Check Domain DNS Records interface.

DNS_Check_Result


Parameter	Required	Type	Description
host	No	String	The CNAME host domain.
recordRole	No	String	The service type of the DNS record. Valid value: `WEB` `API` `SIP` `ACCOUNT` `ACME`
checkStatus	No	String	The check status of the DNS record. Valid value: `RESOLVED`: The DNS record is resolved. `NOT_RESOLVED`: The DNS record is not resolved.
resolvedValues	No	Array<String>	The CNAME target domains of the resolved DNS records.
lastCheckedAt	No	Integer	The time when the DNS record was last checked, in Unix timestamp format (milliseconds).
failureReason	No	String	The reason why the most recent check failed.

Response parameters


Parameter	Type	Description
requestId	String	The unique ID of the request, which can be used to quickly locate the request.
code	String	The HTTP status code of the request. `200`: Request succeeded. Non-200 value: Request failed.
message	String	The status message of the request.
detailMessage	String	The detailed error information. When the request is successful, this parameter returns empty.
result	Object<Domain_Detail>	The details of the created domain.

Domain_Detail


Parameter	Type	Description
id	String	The domain ID.
domain	String	The domain name.
regionCode	String	The region code.
regionName	String	The region name.
domainStatus	String	The status of the domain. `ACTIVE`: The domain is active. `DISABLED`: The domain is disabled.
certificateManagement	String	The certificate management method. `AUTO`: The certificate is managed automatically by the platform. `CUSTOM`: The certificate is uploaded by the user.
autoRenewEnabled	Boolean	Whether automatic certificate renewal is enabled. `true`: Enabled. `false`: Disabled.
certificateStatus	String	The deployment status of the certificate. `NOT_DEPLOYED`: The certificate is not deployed. `PENDING`: The certificate is being deployed. `DEPLOYED`: The certificate is deployed. `FAILED`: The certificate deployment failed. `EXPIRED`: The certificate is expired.
renewalStatus	String	The renewal status of the certificate. `IDLE`: No certificate renewal is in progress. `RENEWING`: The certificate is being renewed. `RENEW_FAILED`: The certificate renewal failed.
certificateSource	String	The source of the certificate. `LETS_ENCRYPT`: The certificate is issued by Let's Encrypt automatically. `CUSTOM_UPLOAD`: The certificate is uploaded by the user manually.
certificateAuthority	String	The identifier of the certificate authority for manual certificate deployment.
sourceType	String	The source type of the domain. `USER_CONFIGURED`: The domain is configured by the user. `BYOI_DEPLOYMENT`: The domain is deployed by BYOI.
keyAlgorithm	String	The format of private key for manual certificate deployment. `RSA` `EC`
expireTime	Integer	The time when the certificate expires, in Unix timestamp format (milliseconds).
lastFailureCode	String	The error code of the most recent failure.
lastFailureReason	String	The reason for the most recent failure.
lastFailureTime	Integer	The time of the most recent failure, in Unix timestamp format (milliseconds).
createTime	Integer	The time when the domain was created, in Unix timestamp format (milliseconds).
updateTime	Integer	The time when the domain was last updated, in Unix timestamp format (milliseconds).
effectiveDomain	String	The effective domain, which is computed at runtime.
effectiveDomainSource	String	The source of the effective domain. `SELF`: The effective domain is the domain itself. `PARENT`: The effective domain is inherited from the parent. `OFFICIAL`: The effective domain is the official domain.
retryable	Boolean	Whether the most recent failure can be retried. `true`: The failure can be retried. `false`: The failure cannot be retried.
renewalWarning	Boolean	Whether there is a certificate renewal warning. `true`: There is a certificate renewal warning. `false`: There is no certificate renewal warning.
dnsRecords	Array<DNS_Record>	The list of DNS records.
certificate	String	The content of the custom certificate in PEM format.
privateKey	String	The private key of the custom certificate in PEM format.
customCertificateMeta	Object<Custom_Certificate_Meta>	The metadata of the custom certificate.

DNS_Record


Parameter	Type	Description
recordRole	String	The service type of the DNS record. `WEB` `API` `SIP` `ACCOUNT` `ACME`
host	String	The CNAME host domain.
subDomain	String	The subdomain, which is the left prefix of the host domain after the portal domain is removed. For example, the subdomain of `cn-0.dev.ymznas.cn` is `cn-0.dev`.
rootDomain	String	The portal domain.
recordType	String	The record type. `CNAME`
target	String	The CNAME target domain.
checkStatus	String	The check status of the DNS record. `NOT_CHECKED`: The DNS record is not checked. `CHECKING`: The DNS record is being checked. `RESOLVED`: The DNS record is resolved. `NOT_RESOLVED`: The DNS record is not resolved.
resolvedValues	Array<String>	The CNAME target domains of the resolved DNS records.
lastCheckedAt	Integer	The time when the DNS record was last checked, in Unix timestamp format (milliseconds).
failureReason	String	The reason why the most recent check failed.

Custom_Certificate_Meta


Parameter	Type	Description
issuer	String	The X.509 issuer DN of the uploaded certificate.
subject	String	The subject of the certificate.
san	String	The subject alternative names (SANs) of the certificate, separated by commas.
serialNumber	String	The serial number of the certificate.
fingerprint	String	The fingerprint of the certificate.
keyAlgorithm	String	The key algorithm of the certificate. `RSA` `EC`
notBefore	Integer	The time when the certificate takes effect, in Unix timestamp format (milliseconds).
notAfter	Integer	The time when the certificate expires, in Unix timestamp format (milliseconds).

Example

Request example

POST /uc-user/api/v1/domains/regions/cn-0 HTTP/1.1
Host: api.cn.novoone.com
Authorization: Bearer eyJraWQiOiJjbi0wLWtleS0xIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkaXN0cmlidXRvcmV4YW1wbGVAb3V0bG9vay5jb20iLCJncmFudF90eXBlIjoib3BlbmFwaSIsImNsaWVudF9leHQiOnsiZGVzY3JpcHRpb24iOiLnrKzkuInmlrnlkIjkvZzkvJnkvLTlupTnlKgiLCJwYXJ0bmVyIjoi56S65L6L5ZCI5L2c5LyZ5Ly0In0sImNsaWVudF90eXBlIjoib3BlbmFwaSIsImV4cCI6MTc5MTg4MDQwMCwiaWF0IjoxNzkxODU4ODAwLCJqdGkiOiJlYjczYTljNi05NGY1LTQ5MzItODcyYi0yMDUzMzVmMWE4YTkiLCJjbGllbnRfaWQiOiJub3ZvLW9wZW4tcGxhdGZvcm0iLCJ1c2VyX2V4dCI6eyJyb2xlSWRzIjpbM10sInN0eXBlIjoiQURNSU4iLCJ0ZW5hbnRDb2RlIjpudWxsLCJ0eXBlIjoiUF9BQ0NPVU5UIiwidXNlcklkIjozMDc2OTEzNjQ0OTE1OTk4NzIwLCJlbWFpbCI6ImRpc3RyaWJ1dG9yZXhhbXBsZUBvdXRsb29rLmNvbSIsInVzZXJuYW1lIjoiZGlzdHJpYnV0b3JleGFtcGxlQG91dGxvb2suY29tIiwidWNJZCI6MzA3NjkxMzY0NDg5MDgzMjg5Nn19.hTHYgOuTSUnTMWM4NwMB6tPaChCUx2_2SNsSGTpGbIVF1goAOeUi1rbPej1t04EgzC_c6lfRAdf2mB0Uq4JP49DNYKDwbUDerQqc8WeO-RQvd466YJWsGlCJcWEzGaTXPpNG9glzn3i_zArhJN7MyzVKWz5ygKAadH7nQ5RJzLM6sOFnZ5DbTnQ4_uT_P-AdnPcTrlNvP62R58fiKjARMHPR0tHuUA3U0IiMKzH3uRVTyRXY_LccFFVys3Io5J5-ovntsTKaZ0o08kcXh1FJ5BW2Zj_6DJE_-Q1dwzQDkJ7aWJuRNSG30zXakHbuG7UqqFYRG8Y6MUDMoraKaCATKA
Content-Type: application/json
{
  "domain": "claude-doc-test.example.com",
  "certificateManagement": "AUTO",
  "autoRenewEnabled": true,
  "clusterIssuerRef": "letsencrypt-staging",
  "acmeAlias": "acme-alias.com",
  "dnsCheckResults": [
    {
      "host": "claude-doc-test.example.com",
      "recordRole": "WEB",
      "checkStatus": "NOT_RESOLVED",
      "resolvedValues": [],
      "lastCheckedAt": 1791859355018
    }
  ]
}

Response example

HTTP/1.1 200 OK
{
  "result": {
    "id": "2089269871530487810",
    "domain": "novoone.online",
    "regionCode": "cn-0",
    "regionName": "HongKong",
    "domainStatus": "ACTIVE",
    "certificateManagement": "AUTO",
    "autoRenewEnabled": false,
    "certificateStatus": "DEPLOYED",
    "renewalStatus": "NOT_STARTED",
    "certificateAuthority": "letsencrypt-staging",
    "sourceType": "USER_CONFIGURED",
    "expireTime": 1794728675000,
    "createTime": 1786955728815,
    "updateTime": 1791859069082,
    "dnsRecords": [
      {
        "recordRole": "ACCOUNT",
        "host": "account.novoone.online",
        "subDomain": "account",
        "rootDomain": "novoone.online",
        "recordType": "CNAME",
        "target": "account.cn-0.test.novo-one.com.",
        "checkStatus": "RESOLVED",
        "resolvedValues": [
          "account.cn-0.test.novo-one.com."
        ],
        "lastCheckedAt": 1786956149536,
        "failureReason": "DNS lookup failed [default]: DNS name not found [response code 3]"
      },
      {
        "recordRole": "WEB",
        "host": "novoone.online",
        "rootDomain": "novoone.online",
        "recordType": "CNAME",
        "target": "cn-0.test.novo-one.com.",
        "checkStatus": "RESOLVED",
        "resolvedValues": [
          "cn-0.test.novo-one.com."
        ],
        "lastCheckedAt": 1786956149933,
        "failureReason": "DNS lookup failed [default]: DNS name not found [response code 3]"
      },
      {
        "recordRole": "API",
        "host": "api.novoone.online",
        "subDomain": "api",
        "rootDomain": "novoone.online",
        "recordType": "CNAME",
        "target": "api.cn-0.test.novo-one.com.",
        "checkStatus": "RESOLVED",
        "resolvedValues": [
          "api.cn-0.test.novo-one.com."
        ],
        "lastCheckedAt": 1786956149935,
        "failureReason": "DNS lookup failed [default]: DNS name not found [response code 3]"
      },
      {
        "recordRole": "SIP",
        "host": "sip.novoone.online",
        "subDomain": "sip",
        "rootDomain": "novoone.online",
        "recordType": "CNAME",
        "target": "sip.cn-0.test.novo-one.com.",
        "checkStatus": "RESOLVED",
        "resolvedValues": [
          "sip.cn-0.test.novo-one.com."
        ],
        "lastCheckedAt": 1786956149937,
        "failureReason": "DNS lookup failed [default]: DNS name not found [response code 3]"
      },
      {
        "recordRole": "ACME",
        "host": "_acme-challenge.novoone.online",
        "subDomain": "_acme-challenge",
        "rootDomain": "novoone.online",
        "recordType": "CNAME",
        "target": "novoone.online.acme-alias.com.",
        "checkStatus": "RESOLVED",
        "resolvedValues": [
          "novoone.online.acme-alias.com."
        ],
        "lastCheckedAt": 1786956149938,
        "failureReason": "DNS lookup failed [default]: DNS name not found [response code 3]"
      }
    ]
  },
  "requestId": "715ec9d35f10dd99687195ff2feef996",
  "code": "200",
  "message": "SUCCESS"
}