LinkShrink API Documentation

Welcome to LinkShrink, the free URL shortener that respects your privacy. This API allows you to shorten URLs, create custom aliases, generate QR codes, and track basic analytics—all without requiring an API key or user account.

Authentication

None required. All endpoints are publicly accessible. There are no API keys, no OAuth flows, no JWT tokens. Just call the endpoints directly.

Rate Limits

To ensure fair usage and prevent abuse, LinkShrink enforces the following rate limits:

• Anonymous requests: 30 requests per minute per IP address
• Burst allowance: Up to 60 requests in a 10-second burst, then throttled
• Headers: Check X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset in response headers

Shorten a URL

Create a short link from a long URL. Optionally specify a custom alias.

Request Body

Example Request

curl -X POST "https://linkshrink.dev/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/softvoyagers/linkshrink-api",
    "alias": "gh-linkshrink"
  }'

Example Response

{
  "status": "success",
  "data": {
    "shortUrl": "https://linkshrink.dev/gh-linkshrink",
    "originalUrl": "https://github.com/softvoyagers/linkshrink-api",
    "alias": "gh-linkshrink",
    "qrCode": "https://linkshrink.dev/gh-linkshrink/qr",
    "analytics": "https://linkshrink.dev/gh-linkshrink/stats",
    "createdAt": "2026-02-13T12:00:00.000Z"
  }
}

Redirect to Target URL

Access a short link to be redirected to the original URL. This increments the click count.

Path Parameters

Example

https://linkshrink.dev/gh-linkshrink

→ Redirects to: https://github.com/softvoyagers/linkshrink-api

Get Analytics

Retrieve click statistics for a shortened link. No authentication required—analytics are public.

Path Parameters

Example Request

curl "https://linkshrink.dev/gh-linkshrink/stats"

Example Response

{
  "status": "success",
  "data": {
    "alias": "gh-linkshrink",
    "originalUrl": "https://github.com/softvoyagers/linkshrink-api",
    "shortUrl": "https://linkshrink.dev/gh-linkshrink",
    "clicks": 1247,
    "createdAt": "2026-02-13T12:00:00.000Z",
    "lastClickedAt": "2026-02-13T14:32:15.000Z",
    "topCountries": [
      { "country": "US", "clicks": 542 },
      { "country": "DE", "clicks": 318 },
      { "country": "GB", "clicks": 201 }
    ],
    "topReferrers": [
      { "referrer": "twitter.com", "clicks": 423 },
      { "referrer": "reddit.com", "clicks": 298 },
      { "referrer": "direct", "clicks": 526 }
    ]
  }
}

Get QR Code

Retrieve a QR code image for a shortened link. Returns a PNG image that can be embedded or downloaded.

Path Parameters

Query Parameters (Optional)

Example

https://linkshrink.dev/gh-linkshrink/qr

→ Returns PNG image of QR code

https://linkshrink.dev/gh-linkshrink/qr?size=500&format=svg

→ Returns SVG image of QR code at 500x500px

Custom Aliases

When creating a short link, you can specify a custom alias to make your link more memorable and brandable. If no alias is provided, LinkShrink will generate a random 6-character code.

Alias Rules

• Length: 3-30 characters
• Allowed characters: Alphanumeric (a-z, A-Z, 0-9), hyphens (-), underscores (_)
• Case-sensitive: MyLink and mylink are different aliases
• First-come, first-served: Aliases are globally unique. If taken, you'll receive a 409 Conflict error
• Reserved words: System paths like api, docs, health are reserved

Error Codes

LinkShrink uses standard HTTP status codes to indicate success or failure.

Error Response Format

{
  "status": "error",
  "message": "Alias 'gh-linkshrink' is already taken",
  "code": "ALIAS_TAKEN"
}

Full Examples

Example 1: Shorten a URL with Auto-Generated Alias

curl -X POST "https://linkshrink.dev/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very-long-url-with-many-parameters"}'

# Response:
{
  "shortUrl": "https://linkshrink.dev/a3f8Kp",
  "qrCode": "https://linkshrink.dev/a3f8Kp/qr",
  ...
}

Example 2: Shorten with Custom Alias

curl -X POST "https://linkshrink.dev/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://softvoyagers.com/blog/best-practices",
    "alias": "sv-blog-best"
  }'

Example 3: Fetch Analytics

curl "https://linkshrink.dev/sv-blog-best/stats"

# Response includes click count, countries, referrers