Domains API
Add and manage custom domains for branded short links (Starter+ via REST; MCP domain tools need Pro+)
Custom domains let you use your own hostname (e.g. go.yourbrand.com) as the base for all your short links. The verification flow uses a DNS TXT record to confirm ownership, followed by a CNAME pointing to AWSYS.CO infrastructure. Custom domain support requires Pro or higher.
Verification Flow
- Call POST /api/user/domains to register the domain. The response includes a
verificationToken. - Add a TXT record at
_awsys-verify.yourdomain.comwith valueawsys-verify=<token>. - Add a CNAME record pointing
yourdomain.comtocustom.awsys.co. - Call GET /api/user/domains/:domain/verify to trigger DNS verification. Returns
verified: truewhen the TXT record propagates (up to 48 hours). - Call POST /api/user/domains/:domain/activate to enable the domain for link creation.
Base URL
https://awsys.co
Authentication
All domain endpoints require a valid API key (Starter or higher plan). See the Authentication page for details.
Authorization: Bearer YOUR_API_KEY
List Domains
GET /api/user/domains
Response
{
"domains": [
{
"domain": "go.yourbrand.com",
"status": "active",
"sslStatus": "active",
"createdAt": "2026-04-01T10:00:00Z",
"linkCount": 45
}
],
"monthlyPrice": 0
}
curl example
curl https://awsys.co/api/user/domains \
-H "Authorization: Bearer YOUR_API_KEY"
Add a Domain
POST /api/user/domains
Request body
{
"domain": "go.yourbrand.com"
}
Response — 201 Created
{
"domain": "go.yourbrand.com",
"status": "pending_txt",
"verificationToken": "abc123def456",
"txtRecord": {
"name": "_awsys-verify.go.yourbrand.com",
"type": "TXT",
"value": "awsys-verify=abc123def456"
},
"cnameRecord": {
"name": "go.yourbrand.com",
"type": "CNAME",
"value": "custom.awsys.co"
}
}
curl example
curl -X POST https://awsys.co/api/user/domains \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "go.yourbrand.com"}'
Verify a Domain
GET /api/user/domains/:domain/verify
Polls DNS to check whether the TXT record has propagated. Call this endpoint after setting up DNS records. Returns the current status. Poll periodically — DNS propagation can take up to 48 hours.
Response
{
"verified": false,
"status": "pending_txt",
"hint": "TXT record not found yet. DNS changes can take up to 48 hours to propagate."
}
curl example
curl https://awsys.co/api/user/domains/go.yourbrand.com/verify \
-H "Authorization: Bearer YOUR_API_KEY"
Activate a Domain
POST /api/user/domains/:domain/activate
Activates a verified domain for use in link creation. The domain must have status: verified before calling this endpoint.
Response — 200 OK
{
"success": true,
"domain": "go.yourbrand.com",
"status": "active",
"billing": { "free": true }
}
Update Domain Settings
PATCH /api/user/domains/:domain
Update settings on an active domain — set it as your default domain or configure a custom 404 page.
Request body
{
"setDefault": true,
"notFoundPage": {
"type": "redirect",
"redirectUrl": "https://yourbrand.com"
}
}
| Field | Type | Description |
|---|---|---|
setDefault | boolean | Make this domain the default for new links |
notFoundPage.type | string | redirect or html — behavior for unknown slugs on this domain |
notFoundPage.redirectUrl | string | URL to redirect to when type is redirect |
notFoundPage.html | string | Custom HTML served for unknown links when type is html (max 10,000 characters). Scripts, iframes, objects, embeds, event handlers, meta refresh tags and links that are not http, https, mailto or tel are removed, and the page is served in a sandbox with no scripts or forms. Inline CSS and https images and fonts still work. |
Remove a Domain
DELETE /api/user/domains/:domain
Removes the domain from your account and cancels any associated billing. Existing links that used this domain will fall back to awsys.co.
Response — 200 OK
{ "success": true }
Check Domain Availability
GET /api/domains/check/:hostname
Checks whether a hostname is available to be registered as a custom domain.
Response
{
"hostname": "go.yourbrand.com",
"available": true
}
Error Codes
| Code | HTTP | Description |
|---|---|---|
TIER_UPGRADE_REQUIRED | 403 | Custom domains are not available on the Free plan (Starter or higher required). |
INVALID_DOMAIN | 400 | The hostname is not a valid domain format. |
RESERVED_DOMAIN | 400 | This hostname is reserved and cannot be registered. |
DOMAIN_TAKEN | 409 | This domain is already registered to another account. |
DOMAIN_LIMIT_REACHED | 403 | You have reached the maximum number of custom domains for your plan. |
DOMAIN_NOT_FOUND | 404 | Domain not found or does not belong to your account. |
DOMAIN_NOT_VERIFIED | 400 | Cannot activate a domain that has not passed DNS verification. |