UrlShorter documentation

Everything you need to create, manage, and measure short links on urlshorter.cc—from your first link to programmatic integration with the REST API.

Introduction

UrlShorter converts long web addresses into compact, shareable links that redirect visitors to the stored destination. Account-managed links can be reviewed through aggregate activity in the owner dashboard. Links work anywhere a URL works—social bios, SMS messages, email campaigns, printed QR codes, and paid ads.

You can use UrlShorter through the web interface on the homepage (no account required for basic links), or programmatically through the HTTP API described below.

Quick start guide

1. Paste your long URL. Go to the homepage and paste any web address into the shortener box. If you omit the protocol, https:// is added automatically.
2. Choose an optional custom alias. Instead of a random code such as urlshorter.cc/x7k2p9, choose a readable slug such as urlshorter.cc/spring-sale. See alias rules.
3. Copy and share. Your short link is live immediately and served over HTTPS with a temporary HTTP 307 redirect to your destination.
4. Review activity. Sign in with email or Google to manage eligible links in your dashboard and review the aggregate reports available for each one.

Recent guest-link details are stored in the browser, while a signed ownership cookie protects eligible server operations. Signing in can adopt eligible links still represented by that cookie; clearing browser data can remove access before adoption, and no link should be treated as a permanent archival record.

Custom aliases

Custom aliases follow these rules:

• Between 3 and 16 characters long.
• Letters, numbers, hyphens, and underscores only (a–z, A–Z, 0–9, -, _).
• The alias must be unique. If it is taken, you will be asked to choose another.
• Reserved words such as admin, login, and dashboard cannot be used.

Good aliases are short, lowercase, and descriptive: q2-report, menu, or yt-tutorial. For marketing-team naming conventions, read our custom short links guide.

Link analytics

Saved account links record click activity. From your dashboard you can see:

• Click counts—lifetime totals and recent activity.
• Time trends—aggregate redirect activity over the available reporting window.
• Top links—account links ordered by recorded activity.
• Referrer and device summaries—host labels and broad device categories when request signals are available.

These counts can include automated requests and are not unique people, sessions, or conversions. Geography, identity-level visitors, conversion tracking, and data export are not currently provided.

You can append UTM parameters to your destination URL before shortening so clicks appear in Google Analytics alongside UrlShorter statistics. Our UTM parameters guide explains a naming system that scales.

QR codes

Any short link can be turned into a QR code with the free QR code generator. If the QR code encodes an account-managed short link, its owner can review aggregate redirect activity and update the managed destination without changing the printed QR image. Practical setups are covered in QR code marketing.

API overview

The UrlShorter API is a JSON-over-HTTPS interface. Requests are made against the production origin:

Base URL: https://urlshorter.cc/api

This public endpoint powers the interactive guest-link creator and does not accept API keys. It is not a general-purpose server-to-server API. When Turnstile protection is configured, a valid browser challenge token for the link-create action is required; a token-free command-line request is rejected. The web interface uses the signed-in session for account attribution. Send requests as application/json; cross-origin browser access is not supported.

Create a short link

POST /api/links/create creates a new short link.

Request body

{
  "url": "https://example.com/very/long/path?utm_source=newsletter",
  "customAlias": "spring-sale",
  "turnstileToken": "..."
}

Example request

const response = await fetch("/api/links/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/very/long/path", turnstileToken })
})

Successful response

{
  "success": true,
  "data": {
    "originalUrl": "https://example.com/very/long/path",
    "shortCode": "x7k2p9",
    "clicks": 0,
    "createdAt": "2026-07-01T10:15:00.000Z",
    "isActive": true
  }
}

The resulting short link is https://urlshorter.cc/{shortCode}.

Error handling

Errors return a JSON body with an error message and a matching HTTP status:

{ "error": "Custom alias must be between 3 and 16 characters" }

Limits and fair use

• The public endpoint is intended for light, interactive use. It is not a supported bulk API; requests may be throttled and should honor 429 and Retry-After responses.
• Challenge tokens are short-lived and bound to the expected action and hostname. They are not API credentials and must not be reused or fabricated.
• Destinations are validated, optional reputation checks apply only when configured, and reported links can be reviewed or revoked. No automated control guarantees safety. See our Terms of Service.
• The endpoint does not expose a user-selected expiration value. Availability can still change because of guest retention, owner action, moderation, service policy, or the destination itself.

Building an integration and need something the API does not cover yet? Tell us about your use case. API keys, bulk operations, read, update, and delete endpoints, idempotency keys, and analytics exports are not current features. For a broader look at automation patterns, read automating link creation.