kna.sh documentation

Short link formats

Every short link has an automatic ID shaped like AAAAAAAA.AAAA (hex timestamp + unique suffix). Destinations are always http or https URLs.

https://kna.sh/578a4ef8.1a2b
https://kna.sh/promo/578a4ef8.1a2b          # with path prefix
https://acme.g.kna.sh/578a4ef8.1a2b         # branded host
https://go.mydomain.com/578a4ef8.1a2b       # custom domain (verified)
https://go.kna.sh/MyCampaign                # vanity slug

Append ~ to expand a link without redirecting (e.g. https://kna.sh/578a4ef8.1a2b~).

Path prefixes on kna.sh

Organization admins can claim a unique path prefix so automatic short links look like:

https://kna.sh/{prefix}/{link_id}

1–12 characters: letters, digits, . _ ~ -
Profanity filtered; cannot match reserved paths (login, about, links, …)
Unique across all organizations (case-insensitive)

Configure under Account in the console, or PATCH /api/v1/customer with path_prefix.

Bare IDs (https://kna.sh/{id}) still work after you claim a prefix.

Branded hosts (*.g.kna.sh)

Optionally claim a label under g.kna.sh (min 3 characters, not purely numeric):

https://acme.g.kna.sh/{id}
https://acme.g.kna.sh/{prefix}/{id}   # if path prefix is set

Labels are unique platform-wide. Platform DNS maps *.g.kna.sh to the kna.sh service. Set the label in Account or via hostname on PATCH /api/v1/customer.

Custom domains (CNAME)

Use your own hostname (for example go.mydomain.com) so short links look fully on-brand. Traffic reaches kna.sh through a DNS CNAME to the shared target cd.kna.sh.

Requirements

You control DNS for the domain (or subdomain) you want to use
A subdomain is recommended (apex domains often cannot use CNAME)
Admin role on your kna.sh organization

Setup steps

Choose a hostname
Example: go.mydomain.com or links.brand.com. You cannot use *.kna.sh or other platform hosts.
Create the CNAME in DNS
At your DNS provider, add a record:
```
go.mydomain.com.   CNAME   cd.kna.sh.
```
TTL can be low (e.g. 300s) while testing. Propagation may take a few minutes to hours.
Claim the domain in kna.sh
Open console.kna.sh/account → Custom domain, enter the hostname (e.g. go.mydomain.com), and Save branding. The domain is reserved for your organization but remains unverified until DNS checks succeed.
Verify DNS
Click Verify DNS (or call POST /api/v1/customer/custom-domain/verify). kna.sh looks up the CNAME chain and expects it to resolve to cd.kna.sh.
Use verified short links
After verification, new and existing automatic short URLs for your org prefer:
```
https://go.mydomain.com/{id}
https://go.mydomain.com/{prefix}/{id}   # if you also set a path prefix
```
Only links that belong to your organization resolve on that host.

DNS checklist

Item	Value
Record type	`CNAME`
Name / host	Your subdomain (e.g. `go` or `go.mydomain.com`)
Target / value	`cd.kna.sh`
Proxy mode	Prefer DNS-only / grey-cloud if your provider offers a proxy (Cloudflare, etc.)

Verify from the command line

dig +short CNAME go.mydomain.com
# expect: cd.kna.sh.

# or
host -t CNAME go.mydomain.com

API

# Claim domain (session or admin Bearer not required — use session / cookie from console)
curl -X PATCH https://api.kna.sh/api/v1/customer \
  -H "Content-Type: application/json" \
  -H "Cookie: knash_session=…" \
  -d '{"custom_domain":"go.mydomain.com"}'

# Re-check CNAME
curl -X POST https://api.kna.sh/api/v1/customer/custom-domain/verify \
  -H "Cookie: knash_session=…"

Response fields include custom_domain, custom_domain_verified, and custom_domain_cname_target (default cd.kna.sh).

Troubleshooting

Verification fails — confirm the CNAME is published, not a flat A record, and that the name matches exactly what you entered (no extra path or https://).
Domain already taken — another organization claimed that hostname.
Links still show kna.sh — domain is saved but not verified yet; run Verify DNS.
HTTPS / certificate errors — TLS for customer hostnames is handled on the kna.sh edge (load balancer). After DNS is correct, allow time for certificate provisioning if a new hostname was just added. Contact support if the CNAME is verified but HTTPS fails.
Clearing a domain — set custom domain to empty in Account and save; the claim is released for others.

Security: Unverified custom domains do not serve your short links. Only a verified domain on your organization will redirect your link IDs.

Vanity (custom) paths

Optional custom slugs keep letter casing when created; lookup is case-insensitive. Reserved names (e.g. login, about) cannot be used.

Where a vanity path is served (same link, several hosts):

Always: https://go.kna.sh/{slug}
If your org has a path prefix: https://kna.sh/{prefix}/{slug}
If you have a verified custom domain: https://go.mydomain.com/{slug}

The short URL shown in the console prefers a verified custom domain, then a kna.sh path prefix, then go.kna.sh.

Which host is used?

For automatic (non-vanity) short URLs, kna.sh picks the first applicable option:

Verified custom domain
Branded *.g.kna.sh hostname
kna.sh (with path prefix when claimed)

Vanity slugs always use go.kna.sh, independent of branding.

Console & API

Management console: console.kna.sh
API usage guide: kna.sh/api-docs
Interactive OpenAPI: api.kna.sh/docs

Documentation