Skip to main content

​
Get Server Subdomain

Retrieve the subdomain for a server. 
curl -X GET https://api.stellarstack.io/domains/{serverId}/subdomain \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
serverId
string
required
Server ID

​
Response

If no subdomain is claimed:
​
claimed
boolean
Always false when no subdomain exists
If subdomain is claimed:
​
claimed
boolean
Always true
​
subdomain
string
Subdomain name (e.g., “my-server”)
​
fullDomain
string
Full domain including base (e.g., “my-server.stellarstack.io”)
​
createdAt
string
ISO 8601 timestamp

​
Claim Subdomain

Claim a subdomain for a server. This creates a DNS record if Cloudflare integration is enabled. 
curl -X POST https://api.stellarstack.io/domains/{serverId}/subdomain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "my-awesome-server"
  }'

​
Path Parameters

​
serverId
string
required
Server ID

​
Request Body

​
subdomain
string
required
Subdomain to claim (3-32 characters, lowercase alphanumeric with hyphens, cannot start or end with hyphen)

​
Response

201 Created
​
success
boolean
Always true
​
subdomain
string
Claimed subdomain name
​
fullDomain
string
Full domain (subdomain.base-domain)
​
dnsConfigured
boolean
Whether DNS record was created automatically
​
note
string
Note about manual DNS configuration (if Cloudflare not enabled)

​
Error Responses

400 Bad Request
​
error
string
Error message (e.g., “Invalid subdomain”, “This subdomain is reserved”, “Server already has a subdomain”, “Subdomain is already taken”)
404 Not Found - Server not found 500 Internal Server Error - Failed to create DNS record
​
error
string
Error message
​
details
string
Detailed error from DNS provider

​
Reserved Subdomains

The following subdomains are reserved and cannot be claimed:
  • www
  • api
  • admin
  • panel
  • dashboard
  • mail
  • ftp
  • sftp
  • ssh

​
Release Subdomain

Release a claimed subdomain and remove the DNS record. 
curl -X DELETE https://api.stellarstack.io/domains/{serverId}/subdomain \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
serverId
string
required
Server ID

​
Response

​
success
boolean
Always true on successful deletion
404 Not Found - Server does not have a subdomain

​
List Custom Domains

Get all custom domains for a server. 
curl -X GET https://api.stellarstack.io/domains/{serverId}/domains \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
serverId
string
required
Server ID

​
Response

Returns an array of custom domain objects.
​
id
string
Domain ID
​
domain
string
Domain name (e.g., “example.com”)
​
verified
boolean
Whether domain ownership has been verified
​
verifyCode
string
Verification code to add as TXT record
​
createdAt
string
ISO 8601 timestamp

​
Add Custom Domain

Add a custom domain to a server. Returns verification instructions. 
curl -X POST https://api.stellarstack.io/domains/{serverId}/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com"
  }'

​
Path Parameters

​
serverId
string
required
Server ID

​
Request Body

​
domain
string
required
Domain name (4-253 characters, valid domain format)

​
Response

201 Created
​
success
boolean
Always true
​
id
string
Domain ID
​
domain
string
Domain name
​
verified
boolean
Always false for newly added domains
​
verifyCode
string
Verification code for DNS TXT record
​
instructions
object
DNS configuration instructions

​
Error Responses

400 Bad Request
​
error
string
Error message (e.g., “Invalid domain format”, “Domain is already registered”)

​
Verify Domain Ownership

Verify ownership of a custom domain by checking the DNS TXT record. 
curl -X POST https://api.stellarstack.io/domains/{serverId}/domains/{domainId}/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
serverId
string
required
Server ID
​
domainId
string
required
Domain ID

​
Response

If already verified:
​
verified
boolean
Always true
​
message
string
“Domain is already verified”
If verification successful:
​
verified
boolean
Always true
​
message
string
“Domain verified successfully”

​
Error Responses

400 Bad Request - Verification failed
​
verified
boolean
Always false
​
message
string
Error message
​
found
string[]
TXT records found (if verification code not found)
​
expected
string
Expected verification code
404 Not Found - Domain not found 500 Internal Server Error - DNS lookup failed
​
verified
boolean
Always false
​
message
string
DNS error message

​
Remove Custom Domain

Remove a custom domain from a server. 
curl -X DELETE https://api.stellarstack.io/domains/{serverId}/domains/{domainId} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
serverId
string
required
Server ID
​
domainId
string
required
Domain ID

​
Response

​
success
boolean
Always true on successful deletion
404 Not Found - Domain not found

Build docs developers (and LLMs) love

Get started for freeTalk to us