Domains API

Add and manage custom domains for your short links.

Custom domains let your short links live on your own host, for example go.example.com, instead of trimlink.co. The setup has three steps:

  1. Add the domain with the API. The response lists the DNS records to create.
  2. Create the routing record. A subdomain uses a CNAME to cname.trimlink.co, which also proves ownership. A root domain uses an A record on @ to 76.76.21.21 plus the TXT record to prove ownership.
  3. Click Verify on the domain in Dashboard, Domains. Verification is finished in the dashboard. The status endpoint below shows progress but does not mark a domain as verified.

Once verified is true, new links can use the domain. Custom domains come with every plan, and API access starts at Pro.

GET/api/v1/domains

List your custom domains.

Scope: domains:read

Request

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

Response

200Response
{
  "success": true,
  "data": [
    {
      "id": "6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
      "domain": "go.example.com",
      "verified": true,
      "verificationToken": "a3f5d9c7e8b2...",
      "lastCheckedAt": "2026-02-01T09:00:00.000Z",
      "lastStatus": "fully_configured",
      "setupReminderSentAt": null,
      "createdAt": "2026-01-31T12:00:00.000Z",
      "updatedAt": "2026-02-01T09:00:00.000Z",
      "isApex": false,
      "routingRecord": { "type": "CNAME", "host": "go", "value": "cname.trimlink.co" }
    }
  ]
}
POST/api/v1/domains

Add a custom domain. The response holds the DNS records to create. routingRecord.host is the name to enter at most DNS providers.

Scope: domains:write

Parameters

NameTypeRequiredDescription
domainstringYesHost name such as go.example.com, without https:// or a path.

Request

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"}'

Response

201Response
{
  "success": true,
  "data": {
    "id": "6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
    "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",
    "cnameRecordTTL": 3600,
    "isApex": false,
    "routingRecord": { "type": "CNAME", "host": "go", "value": "cname.trimlink.co" },
    "createdAt": "2026-01-31T12:00:00.000Z"
  }
}
GET/api/v1/domains/:id

Get one domain with its DNS records.

Scope: domains:read

Request

curl https://trimlink.co/api/v1/domains/6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response
{
  "success": true,
  "data": {
    "id": "6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
    "domain": "go.example.com",
    "verified": true,
    "verificationToken": "a3f5d9c7e8b2...",
    "txtRecordHost": "_trimlink-verification.go.example.com",
    "txtRecordValue": "trimlink-verify=a3f5d9c7e8b2...",
    "cnameRecordHost": "go.example.com",
    "cnameRecordValue": "cname.trimlink.co",
    "cnameRecordTTL": 3600,
    "isApex": false,
    "routingRecord": { "type": "CNAME", "host": "go", "value": "cname.trimlink.co" },
    "createdAt": "2026-01-31T12:00:00.000Z"
  }
}
GET/api/v1/domains/:id/status

Check the live DNS setup of a domain, with a list of issues and the records still to fix. Results may be cached for a few minutes (cachedStatus). Up to 30 checks per hour per domain.

Scope: domains:read

Request

curl https://trimlink.co/api/v1/domains/6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d/status \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

200Response
{
  "success": true,
  "data": {
    "id": "6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
    "domain": "go.example.com",
    "verified": true,
    "verificationToken": "a3f5d9c7e8b2...",
    "status": "txt_verified",
    "txtRecord": { "verified": true, "found": true, "value": "trimlink-verify=a3f5d9c7e8b2..." },
    "cnameRecord": {
      "configured": false,
      "found": false,
      "actualTarget": null,
      "expectedTarget": "cname.trimlink.co"
    },
    "connection": { "connected": true },
    "lastCheckedAt": "2026-02-01T09:00:00.000Z",
    "cachedStatus": false,
    "issues": ["Domain verified via TXT, but CNAME not configured - routing not set up"],
    "recommendations": ["Add a CNAME record to enable routing:"]
  }
}
DELETE/api/v1/domains/:id

Remove a custom domain. Links that use it stay in your account but stop opening on that host.

Scope: domains:write

Request

curl -X DELETE https://trimlink.co/api/v1/domains/6b5a4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d \
  -H "Authorization: Bearer tk_live_your_api_key"

Response

204 No Content

Errors

These endpoints use the standard error response format. DNS changes can take minutes to hours to spread, so wait and check again rather than adding the domain a second time.

CodeWhen it happens
400Invalid domain name, a domain that is already registered, or the plan domain limit is reached (Pro 5, Growth 15, Teams and Enterprise unlimited).
403The key lacks domains:read or domains:write.
404The domain does not exist in your workspace.
429More than 5 domains added in an hour, or more than 30 status checks in an hour for one domain.

Domain Status Values

StatusMeaning
pendingOwnership is not proven yet. No TXT record and no correct CNAME was found.
txt_verifiedOwnership is proven, but the routing record does not point to TrimLink yet.
fully_configuredOwnership is proven and the routing record points to TrimLink.
misconfiguredA CNAME exists but points somewhere other than cname.trimlink.co.