Domains API

Custom domains let your short links live on your own branded host (for example go.example.com) instead of trimlink.co. The Domains API mirrors the dashboard flow: you register a domain, configure two DNS records, then trigger verification. Once a domain reports fully_configured it can be used as the host for any new short link.

Domains move through a small set of status values (listed at the bottom of this page) as TrimLink polls your DNS. A domain is only usable once both the TXT verification record and the CNAME record resolve correctly.

List all custom domains.

curl https://trimlink.co/api/v1/domains \
  -H "Authorization: Bearer tk_live_your_api_key"

{
  "success": true,
  "data": [
    {
      "id": "7a1b2c3d-4e5f-4061-8273-849506a7b8c9",
      "domain": "go.example.com",
      "verified": true,
      "lastStatus": "fully_configured",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

Add a custom domain for verification.

curl -X POST https://trimlink.co/api/v1/domains \
  -H "Authorization: Bearer tk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "go.example.com"}'

{
  "success": true,
  "data": {
    "id": "2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d",
    "domain": "go.example.com",
    "verified": false,
    "verificationToken": "a3f5d9c7e8b2...",
    "txtRecordHost": "_trimlink-verification.go.example.com",
    "txtRecordValue": "trimlink-verify=a3f5d9c7e8b2...",
    "cnameRecordHost": "go.example.com",
    "cnameRecordValue": "cname.trimlink.co"
  }
}

Get domain details.

curl https://trimlink.co/api/v1/domains/2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d \
  -H "Authorization: Bearer tk_live_your_api_key"

{
  "success": true,
  "data": {
    "id": "2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d",
    "domain": "go.example.com",
    "verified": false,
    "lastStatus": "txt_missing",
    "lastCheckedAt": "2026-01-31T12:00:00Z",
    "createdAt": "2026-01-31T10:00:00Z"
  }
}

Trigger domain verification check.

{
  "success": true,
  "data": {
    "id": "2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d",
    "domain": "go.example.com",
    "verified": true,
    "lastStatus": "fully_configured"
  }
}

Check domain DNS configuration status.

curl https://trimlink.co/api/v1/domains/2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d/status \
  -H "Authorization: Bearer tk_live_your_api_key"

{
  "success": true,
  "data": {
    "txtConfigured": true,
    "cnameConfigured": true,
    "status": "fully_configured"
  }
}

Delete a custom domain.

curl -X DELETE https://trimlink.co/api/v1/domains/2b9d8c1a-3e4f-4a6b-8c0d-1f2e3a4b5c6d \
  -H "Authorization: Bearer tk_live_your_api_key"

Errors

These endpoints use the standard error response format. Common domain-specific failures:

Usage Notes

• DNS changes can take minutes to hours to propagate. If verification returns txt_missing or cname_missing, wait and retry the verify call rather than re-adding the domain.
• Use the verify endpoint to trigger an on-demand check; TrimLink also re-checks pending domains periodically in the background.
• Deleting a domain does not delete the links that used it, but those links will stop resolving on the custom host once the CNAME is removed.