Domains API

Add and manage custom domains for branded short links (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 (Pro+ only). 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"
  }
}

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