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

  1. Call POST /api/user/domains to register the domain. The response includes a verificationToken.
  2. Add a TXT record at _awsys-verify.yourdomain.com with value awsys-verify=<token>.
  3. Add a CNAME record pointing yourdomain.com to custom.awsys.co.
  4. Call GET /api/user/domains/:domain/verify to trigger DNS verification. Returns verified: true when the TXT record propagates (up to 48 hours).
  5. 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"
  }
}
FieldTypeDescription
setDefaultbooleanMake this domain the default for new links
notFoundPage.typestringredirect or html — behavior for unknown slugs on this domain
notFoundPage.redirectUrlstringURL to redirect to when type is redirect
notFoundPage.htmlstringCustom 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

CodeHTTPDescription
TIER_UPGRADE_REQUIRED403Custom domains are not available on the Free plan (Starter or higher required).
INVALID_DOMAIN400The hostname is not a valid domain format.
RESERVED_DOMAIN400This hostname is reserved and cannot be registered.
DOMAIN_TAKEN409This domain is already registered to another account.
DOMAIN_LIMIT_REACHED403You have reached the maximum number of custom domains for your plan.
DOMAIN_NOT_FOUND404Domain not found or does not belong to your account.
DOMAIN_NOT_VERIFIED400Cannot activate a domain that has not passed DNS verification.