Custom Domains
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
| Method | Path | Scope |
|---|---|---|
GET | /api/v1/domains | domains:read |
POST | /api/v1/domains | domains:write, account-wide key |
POST | /api/v1/domains/{id}/verify | domains: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" }
]
}
}| Field | Notes |
|---|---|
is_owner, can_manage | Whether you own the domain, and whether you can verify it. Only the owner can delete it. |
access_label | Owner, or which workspace gives you access to the domain. |
status | ready, in_progress, not_ready, inactive or deleting. |
dns_status | verified or not_verified. |
tls_status | ready, in_progress or not_ready. |
provisioning_status | pending_dns, pending_tls_staging, pending_tls_production, pending_ingress, ready, error or deleting. |
links_using | Links on the domain, disabled and archived ones included. |
workspace_public_ids | The workspaces the domain is assigned to. |
verification_token | Shown only while the domain waits for DNS (pending_dns). |
verification_failure_count | Failed DNS checks in a row on a verified domain. At 3, the domain is turned off (see custom domains). |
dns | The 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_atandtls_next_retry_at;deletion_requested_at;verification_txt_matchandverification_routing_match;last_verification_check_atandlast_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
| Field | Type | Required | Notes |
|---|---|---|---|
domain | string | Yes | A 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:
| Status | code | When |
|---|---|---|
400 | invalid_request_format | The body isn’t valid JSON. |
400 | invalid_domain | The domain is missing, has a path or port, or isn’t a valid hostname (details.field is domain). |
400 | domain_reserved | The domain belongs to Shortn. |
403 | plan_limit_exceeded | Your plan has no custom domains (required_plan is starter), or you’ve reached its limit (limit and current say how many). |
409 | domain_exists | The 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:
| Status | code | When |
|---|---|---|
400 | invalid_domain_id | The ID isn’t a number. |
400 | domain_inactive | The domain has been turned off. |
403 | forbidden | You can’t manage this domain. |
404 | domain_not_found | No 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:
| Status | code | When |
|---|---|---|
400 | invalid_domain_id | The ID isn’t a number. |
403 | forbidden | You can’t manage the domain, or you aren’t its owner. |
404 | domain_not_found | No domain with this ID that you can reach. |
409 | domain_in_use | Links 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.