URL Shortener API: Automate Short Links in Your App

Creating links by hand is fine until it is not. The moment every order needs a tracking link, every user needs a referral link, or every listing needs a QR code, you need the same thing programmatically. That is what a URL shortener API is for — and it is a small enough surface that you can wire it up over a coffee.

What you can automate

• Per-order or per-user links generated at the moment they are needed.
• Bulk campaign links — one per channel, created from a spreadsheet in a loop instead of by hand.
• QR codes on the fly for tickets, invoices, labels and packing slips.
• Click data pulled back into your own dashboard, so the numbers live where your team already looks.

If you are not sure you need the API yet, the honest test is volume and repetition: if you are doing the same thing in a browser more than a few times a week, automate it.

Authenticate

Get your key from your account page and send it as an X-Api-Key header on every request. Two rules that are not negotiable: keep the key server-side — anything in front-end JavaScript is public, and a leaked key lets strangers create links in your name — and rotate it immediately if it ever lands in a repository or a log.

Create a link

One POST to /api/getLink.json with the destination. You can pass an alias, a mode, an expiry and a password in the same call:

curl -X POST https://urlik.xyz/api/getLink.json -H "X-Api-Key: YOUR_KEY" -d "url=https://example.com/very/long/path" -d "alias=spring-sale"

The response is JSON containing the short URL, its QR URL and its stats URL. Links created with a key are attached to your account, so they show up in your dashboard and can be edited later.

A detail worth knowing before you build: an alias is unique across the service. If spring-sale is taken you get an error, not a silent fallback — so either handle that case or namespace your aliases (acme-spring-sale).

Generate a QR code

GET /api/qr.json takes the data plus optional format, fg, bg, ecc and size, and returns the QR. Point it at a short link rather than a raw long URL — you get a cleaner, sturdier code, and the destination stays editable afterwards. That is the dynamic QR code pattern, done from your backend.

Read the stats

GET /api/stats.json returns totals, a time series, referrers, devices and countries for a link — the same numbers as the stats page, in a form you can put in your own admin panel.

Poll it on a schedule, not on every page load. Click stats are not a real-time system of record, and hammering the endpoint to redraw a chart nobody is watching is how you meet the rate limiter.

Build it so it does not break at 3am

The endpoints are simple; the integrations that fail are the ones that assume nothing ever goes wrong. Four habits that pay for themselves:

• Check the response, always. Every call returns a status — read it. The classic bug is assuming success and storing an error body as if it were a short link, then discovering it on a printed invoice.
• Never block the user on a link. If shortening happens inside checkout, a slow API becomes a slow checkout. Do it in a background job, or fall back to the long URL and retry later. The long URL always works; that is your safety net.
• Cache what does not change. The same destination does not need shortening twice — store the short URL against the source record and reuse it. Cheaper, faster, and your dashboard stays readable.
• Back off on errors. Retry with increasing delays rather than in a tight loop. A rate limit answered with a retry storm stays a rate limit.

Where the API stops

Two honest limits. Rate limits exist and generous is not infinite — batch jobs should be paced, not fired all at once. And the API creates links; it does not decide what should be in them. Tag your links with UTM parameters at creation time (see the UTM guide) or you will automate the production of thousands of links you cannot tell apart in analytics — which is a worse position than doing it by hand.

The short version

One endpoint to create, one for QR, one for stats, a header for auth. Keep the key server-side, check every response, do the work off the critical path, cache what repeats and tag as you create. The full parameter list, error codes and examples live in the API documentation; if you want the conceptual background first, start with what a URL shortener is.