Custom Domains

Point your own subdomain at a deployed project.

Custom domains let you serve a deployed project from your own subdomain (e.g. app.yourdomain.com). Both endpoints require the api-key header.

#Add Custom Domain

PUT/api/v1/vcaas/projects/:projectId/domainUses credits

Attach a custom subdomain (e.g. app.yourdomain.com) to your deployed project.

Deploy first

You MUST deploy your project first AND wait until the deployment status is "success" before calling this endpoint. If the deployment is still in progress or no deployment exists, this returns a NO_DEPLOYMENT error.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Body parameters

Field	Type	Required	Description
`hostname`	string	Yes	The subdomain to add (e.g. `app.yourdomain.com`)

Response fields

Field	Type	Description
`data.success`	boolean	true on success
`data.hostname`	string	The configured hostname
`data.status`	string	`"pending_validation"` initially
`data.dnsRecordsToAdd`	array \| undefined	DNS records to add at your provider
`data.dnsRecordsToAdd[].type`	string	`"CNAME"` or `"TXT"`
`data.dnsRecordsToAdd[].name`	string	DNS record name (zone-relative, e.g. `"app"` or `"_cf-custom-hostname.app"`)
`data.dnsRecordsToAdd[].value`	string	DNS record value (e.g. `"my-app.totalum-project.com"` or verification token)

Example request

bash

curl -X PUT \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.yourdomain.com"}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/domain

Success · 200 OK

json

{
  "errors": null,
  "data": {
    "success": true,
    "hostname": "app.yourdomain.com",
    "status": "pending_validation",
    "dnsRecordsToAdd": [
      { "type": "CNAME", "name": "app", "value": "my-app.totalum-project.com" },
      { "type": "TXT", "name": "_cf-custom-hostname.app", "value": "abc123-verification-token" }
    ]
  }
}

Error · 404

json

{
  "errors": {
    "errorCode": "NO_DEPLOYMENT",
    "errorMessage": "No deployment found. Deploy first and wait until status is \"success\""
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`MISSING_HOSTNAME`	400	hostname is required (e.g. app.yourdomain.com)
`INSUFFICIENT_CREDITS`	402	Not enough credits to add custom domain
`NO_DEPLOYMENT`	404	No deployment found. Deploy first and wait until status is "success"

Note

After configuring DNS, poll GET /projects/:projectId and check customDomain.status until it is "active".

Root domain

Custom domains require a subdomain (e.g. www.yourdomain.com). If you want yourdomain.com (without www) to reach your project, add www.yourdomain.com as the custom domain, then create a redirect in your DNS provider from yourdomain.com to www.yourdomain.com. Most providers offer this as "URL redirect" or "domain forwarding" in their DNS settings.

#Remove Custom Domain

DELETE/api/v1/vcaas/projects/:projectId/domainFree

Detach the custom domain from your project.

Path parameters

Parameter	Type	Description
`projectId`	string	The project ID

Response fields

Field	Type	Description
`data.message`	string	Confirmation message

Example request

bash

curl -X DELETE -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/domain

Success · 200 OK

json

{ "errors": null, "data": { "message": "Custom domain removed" } }

Error · 404

json

{
  "errors": {
    "errorCode": "PROJECT_NOT_FOUND",
    "errorMessage": "Project does not exist or you don't own it"
  },
  "data": null
}

Error codes

Code	HTTP	Meaning
`MISSING_PROJECT_ID`	400	projectId is required
`PROJECT_NOT_FOUND`	404	Project does not exist or you don't own it
`NO_DEPLOYMENT`	404	No deployment found. Deploy first and wait until status is "success"