Skip to content
Custom Domains

Custom Domains

Availability: Custom domains are available on Starter and higher, with more domains on Professional and Agency (see plans). API keys need domains:read to list domains, and domains:write to add, verify and delete them. Adding, verifying and deleting also need an account-wide key, not one restricted to a workspace.

A custom domain lets your short links use your own domain. Domains belong to an account and can be shared with several workspaces, so they’re identified by a numeric id rather than a public ID.

Endpoints

MethodPathScope
GET/api/v1/domainsdomains:read
POST/api/v1/domainsdomains:write, account-wide key
POST/api/v1/domains/{id}/verifydomains:write, account-wide key
DELETE/api/v1/domains/{id}domains:write, account-wide key

A key restricted to a workspace gets 403 account_scoped_api_key_required on the three domains:write endpoints.

The domain object

{
  "id": 14,
  "domain": "go.example.com",
  "is_owner": true,
  "owner_name": "Alex Rivera",
  "can_manage": true,
  "access_label": "Owner",
  "status": "ready",
  "dns_status": "verified",
  "tls_status": "ready",
  "provisioning_status": "ready",
  "tls_phase": "production",
  "is_active": true,
  "is_verified": true,
  "ssl_enabled": true,
  "ready": true,
  "links_using": 37,
  "team_assignment_count": 0,
  "created_at": "2026-08-21T15:02:00Z",
  "verified_at": "2026-08-21T15:20:00Z",
  "verification_failure_count": 0,
  "workspace_public_ids": ["8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10"],
  "dns": {
    "verification_txt": {
      "type": "TXT",
      "name": "_shortn-verify.go.example.com",
      "value": "shortn-domain-verification=4b1f...",
      "ttl": "300"
    },
    "subdomain_cname": {
      "type": "CNAME",
      "name": "go.example.com",
      "value": "edge.shortn.link",
      "ttl": "300"
    },
    "apex_a_records": [
      { "type": "A", "name": "go.example.com", "value": "203.0.113.10", "ttl": "300" }
    ]
  }
}
FieldNotes
is_owner, can_manageWhether you own the domain, and whether you can verify it. Only the owner can delete it.
access_labelOwner, or which workspace gives you access to the domain.
statusready, in_progress, not_ready, inactive or deleting.
dns_statusverified or not_verified.
tls_statusready, in_progress or not_ready.
provisioning_statuspending_dns, pending_tls_staging, pending_tls_production, pending_ingress, ready, error or deleting.
links_usingLinks on the domain, disabled and archived ones included.
workspace_public_idsThe workspaces the domain is assigned to.
verification_tokenShown only while the domain waits for DNS (pending_dns).
verification_failure_countFailed DNS checks in a row on a verified domain. At 3, the domain is turned off (see custom domains).
dnsThe records to create at your DNS provider: the TXT record, plus a CNAME for a subdomain or A records for a root domain.

When they apply, the object also has:

  • owner_avatar_url;
  • workspace_links_using;
  • tls_ready_at, last_tls_error, tls_last_check_at and tls_next_retry_at;
  • deletion_requested_at;
  • verification_txt_match and verification_routing_match;
  • last_verification_check_at and last_verification_error.

List domains

Returns the domains you own and the ones assigned to your workspaces. A key restricted to a workspace lists only the domains assigned to that workspace.

curl https://app.shortn.link/api/v1/domains \
  -H "Authorization: Bearer $SHORTN_API_KEY"

The response has the domains in data, each a full domain object (shortened here):

{
  "data": [
    {
      "id": 14,
      "domain": "go.example.com",
      "status": "ready",
      "ready": true,
      "links_using": 37,
      "workspace_public_ids": ["8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10"]
    }
  ]
}

Add a domain

FieldTypeRequiredNotes
domainstringYesA hostname such as go.example.com. A URL like https://go.example.com is accepted, without a path or port.
curl -X POST https://app.shortn.link/api/v1/domains \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "go.example.com"}'

The response is 201, with the new domain object under domain (shortened here):

{
  "domain": {
    "id": 14,
    "domain": "go.example.com",
    "status": "not_ready",
    "dns_status": "not_verified",
    "provisioning_status": "pending_dns",
    "verification_token": "4b1f...",
    "workspace_public_ids": ["8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10"]
  }
}

Shortn assigns the new domain to your personal workspace. Create the records in dns, then verify the domain.

Errors:

StatuscodeWhen
400invalid_request_formatThe body isn’t valid JSON.
400invalid_domainThe domain is missing, has a path or port, or isn’t a valid hostname (details.field is domain).
400domain_reservedThe domain belongs to Shortn.
403plan_limit_exceededYour plan has no custom domains (required_plan is starter), or you’ve reached its limit (limit and current say how many).
409domain_existsThe domain has already been added.

Verify a domain

Checks the domain’s DNS records now and moves it on to SSL setup when they match. You need to be able to manage the domain (can_manage).

curl -X POST https://app.shortn.link/api/v1/domains/14/verify \
  -H "Authorization: Bearer $SHORTN_API_KEY"

The response is 200 once the domain is ready, and 202 while it’s still being set up. It has the domain object (shortened here) and what the check found:

{
  "domain": { "id": 14, "domain": "go.example.com", "status": "in_progress" },
  "verification": {
    "verified": true,
    "txt": {
      "host": "_shortn-verify.go.example.com",
      "expected": "shortn-domain-verification=4b1f...",
      "found": ["shortn-domain-verification=4b1f..."],
      "match": true
    },
    "routing": {
      "cname_target": "edge.shortn.link",
      "found_cname": "edge.shortn.link",
      "cname_match": true,
      "a_match": false,
      "any_route_ok": true
    }
  }
}

When the records don’t match yet, verified is false and verification.error says why.

Errors:

StatuscodeWhen
400invalid_domain_idThe ID isn’t a number.
400domain_inactiveThe domain has been turned off.
403forbiddenYou can’t manage this domain.
404domain_not_foundNo domain with this ID that you can reach.

Delete a domain

Only the domain’s owner can delete it. A domain that still has links can’t be deleted, disabled and archived links included. Delete those links or move them to another domain first.

curl -X DELETE https://app.shortn.link/api/v1/domains/14 \
  -H "Authorization: Bearer $SHORTN_API_KEY"

The response is 202. The domain object (shortened here) shows status deleting while Shortn removes the domain:

{
  "deleted": true,
  "id": 14,
  "domain": { "id": 14, "domain": "go.example.com", "status": "deleting" }
}

Errors:

StatuscodeWhen
400invalid_domain_idThe ID isn’t a number.
403forbiddenYou can’t manage the domain, or you aren’t its owner.
404domain_not_foundNo domain with this ID that you can reach.
409domain_in_useLinks still use the domain. links_using says how many.
{
  "code": "domain_in_use",
  "error": "This domain is still used by 3 links, including disabled and archived ones. Delete those links or move them to another domain first.",
  "hint": "Delete the domain's links or move them to another domain, then delete it.",
  "details": { "links_using": 3 },
  "links_using": 3
}

Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.

Last updated on