TidyURL docs

Overview

TidyURL is a fast, privacy-friendly, open-source link shortener that runs on your own domain. Turn a long, messy URL into go.yoursite.com/launch, share it anywhere, and see how many real people clicked — not crawlers and link previews.

Every link can forward UTM tags, show a custom social preview, expire on a date, and come with a QR code.

Getting started

TidyURL is open source and self-hosted. You run your own copy and sign in as the owner.

1. Clone the repository from GitHub and deploy it to your own hosting.
2. Connect a Postgres database with auth and run the included migrations.
3. Turn on Google sign-in in your auth service.
4. Open /admin and sign in.
5. Add a domain, then create your first link.

Your admin account

The first person to sign in automatically becomes the admin. Anyone who signs in after that sees a "not an admin" message and can't create or edit links. Sign in yourself right after deploying.

Connect a domain

Use a short subdomain you already own, like go.yoursite.com or link.yoursite.com. In the admin area, open Domains, add the hostname, then point it at your TidyURL deployment.

DNS records

At your DNS provider (Cloudflare, Namecheap, GoDaddy…), add the records your host gives you when you connect the domain — usually an A record for the subdomain plus a TXT record to prove ownership:

Type  Name   Value
A     go     <your host's IP address>
TXT   _host  <verification code from your host>

Changes usually take a few minutes, occasionally a few hours. Once it's live, mark the domain as verified in the Domains tab.

HTTPS & SSL

A free SSL certificate is issued automatically once DNS points at your deployment, so every link works over https://. There's nothing to buy or renew.

Create links

Open Links → New link, pick a domain, choose a slug (or leave it blank for a random one) and paste the destination URL. Save, and the link works immediately.

UTM forwarding

With Forward parameters on, anything added to the short link is passed through to the destination:

go.yoursite.com/launch?utm_source=newsletter
→ https://yoursite.com/pricing?utm_source=newsletter

Social previews

Set an optional title, description and image. When a link is shared on X, LinkedIn, Slack or iMessage, the preview card shows your text instead of whatever the destination page has.

Expiry & fallback

Give a link an expiry date for launches and limited offers. After it expires, visitors go to your fallback URL — or see a "link expired" page if you didn't set one.

QR codes

Every link has a QR code in the Links table. Download it for slides, flyers or packaging; scans count as clicks like any other.

Click analytics

Click the chart icon on any link to see clicks over time, split into humans and bots, plus top referrers, devices and countries.

Bot filtering

Every click is checked against known crawlers, social preview fetchers and headless browsers. Bot clicks are stored separately so your headline number is people only.

TidyMetrics webhook

Using TidyMetrics? Paste its webhook URL in Settings. Each human click is sent over so your revenue attribution knows which short link brought the visitor:

{
  "event": "link_click",
  "slug": "launch",
  "domain": "go.yoursite.com",
  "destination": "https://yoursite.com/pricing",
  "referrer": "https://news.ycombinator.com/",
  "device": "desktop",
  "country": "US"
}

How redirects work

1. A visitor opens go.yoursite.com/launch.
2. TidyURL finds the link by domain and slug.
3. The click is logged and checked for bots.
4. The visitor gets a 307 redirect to the destination — usually in a few milliseconds.

Missing or archived links return 404; expired links without a fallback return 410.

FAQs