LinkShrink API Documentation

curl -X POST "https://linkshrink.dev/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very/long/path?utm_source=email",
    "customAlias": "my-campaign",
    "ttl_seconds": 86400
  }'

{
  "status": "success",
  "data": {
    "code": "my-campaign",
    "shortUrl": "https://linkshrink.dev/my-campaign",
    "previewUrl": "https://linkshrink.dev/preview/my-campaign",
    "qrCode": "https://linkshrink.dev/api/v1/qr/my-campaign.png",
    "analytics": "https://linkshrink.dev/api/v1/stats/my-campaign",
    "deleteToken": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6",
    "passwordProtected": false,
    "originalUrl": "https://example.com/very/long/path?utm_source=email",
    "createdAt": "2026-02-20T12:00:00.000Z",
    "expiresAt": "2026-02-21T12:00:00.000Z"
  }
}

curl -X POST "https://linkshrink.dev/api/v1/shorten/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "ttl_seconds": 604800
  }'

{
  "status": "success",
  "data": [
    {
      "url": "https://example.com/page-1",
      "success": true,
      "data": { "code": "xKp2m4a", "shortUrl": "https://linkshrink.dev/xKp2m4a", ... }
    },
    {
      "url": "https://example.com/page-2",
      "success": true,
      "data": { "code": "rNq9jzL", "shortUrl": "https://linkshrink.dev/rNq9jzL", ... }
    }
  ]
}

curl -X POST "https://linkshrink.dev/api/v1/shorten/utm" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/landing",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring-sale",
    "utm_term": "running+shoes",
    "utm_content": "hero-banner"
  }'

{
  "status": "success",
  "data": {
    "code": "abc1234",
    "shortUrl": "https://linkshrink.dev/abc1234",
    "originalUrl": "https://example.com/landing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale&utm_term=running%2Bshoes&utm_content=hero-banner",
    "taggedUrl": "https://example.com/landing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale&utm_term=running%2Bshoes&utm_content=hero-banner",
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "spring-sale",
      "term": "running+shoes",
      "content": "hero-banner"
    },
    "qrCode": "https://linkshrink.dev/api/v1/qr/abc1234.png",
    "deleteToken": "a1b2c3d4..."
  }
}

curl "https://linkshrink.dev/api/v1/expand/my-campaign"

# Response:
# {
#   "status": "success",
#   "data": {
#     "code": "my-campaign",
#     "originalUrl": "https://example.com/very/long/path?utm_source=email"
#   }
# }

curl "https://linkshrink.dev/api/v1/stats/my-campaign"

# Response:
# {
#   "status": "success",
#   "data": {
#     "code": "my-campaign",
#     "originalUrl": "https://example.com/...",
#     "clicks": 142,
#     "clicksByDay": [
#       { "date": "2026-03-10", "clicks": 38 },
#       { "date": "2026-03-09", "clicks": 52 },
#       { "date": "2026-03-08", "clicks": 52 }
#     ],
#     "referrers": [
#       { "domain": "twitter.com", "clicks": 67 },
#       { "domain": "linkedin.com", "clicks": 45 },
#       { "domain": "github.com", "clicks": 30 }
#     ],
#     "countries": [
#       { "country": "US", "clicks": 58 },
#       { "country": "DE", "clicks": 34 },
#       { "country": "PL", "clicks": 28 },
#       { "country": "GB", "clicks": 22 }
#     ],
#     "createdAt": "2026-02-20T12:00:00.000Z",
#     "expiresAt": "2026-02-21T12:00:00.000Z",
#     "lastClicked": "2026-02-20T14:32:11.000Z"
#   }
# }

# For links with private_stats:
curl "https://linkshrink.dev/api/v1/stats/my-campaign?token=YOUR_STATS_TOKEN"

# 401 if token missing/wrong:
# { "error": "Unauthorized", "message": "This link has private analytics..." }

# Export as JSON (default)
curl "https://linkshrink.dev/api/v1/stats/my-campaign/export"

# Export as CSV (opens in Excel/Sheets)
curl "https://linkshrink.dev/api/v1/stats/my-campaign/export?format=csv" -o analytics.csv

# Filter by date range
curl "https://linkshrink.dev/api/v1/stats/my-campaign/export?from=2026-03-01&to=2026-03-14"

# JSON Response:
# {
#   "status": "success",
#   "data": {
#     "code": "my-campaign",
#     "originalUrl": "https://example.com/...",
#     "from": "2026-03-01",
#     "to": "2026-03-14",
#     "totalClicks": 142,
#     "clicksByDay": [
#       { "date": "2026-03-01", "clicks": 12 },
#       { "date": "2026-03-02", "clicks": 28 },
#       ...
#     ]
#   }
# }

# CSV Response:
# date,clicks
# 2026-03-01,12
# 2026-03-02,28
# ...

curl -X POST "https://linkshrink.dev/api/v1/stats/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["my-campaign", "launch-day", "newsletter-42"],
    "tokens": { "my-campaign": "optional-stats-token" }
  }'

# Response (207 Multi-Status):
# {
#   "status": "success",
#   "data": [
#     {
#       "code": "my-campaign",
#       "success": true,
#       "data": { "clicks": 142, "clicksByDay": [...], ... }
#     },
#     {
#       "code": "launch-day",
#       "success": true,
#       "data": { "clicks": 89, "clicksByDay": [...], ... }
#     },
#     {
#       "code": "newsletter-42",
#       "success": false,
#       "error": "Short URL not found or expired"
#     }
#   ]
# }

# Default PNG (512×512px, cyberpunk colors)
curl "https://linkshrink.dev/api/v1/qr/my-campaign.png" --output qr.png

# Custom size (256px)
curl "https://linkshrink.dev/api/v1/qr/my-campaign.png?size=256" --output qr-small.png

# SVG format (scalable, print-ready)
curl "https://linkshrink.dev/api/v1/qr/my-campaign.svg" --output qr.svg

# Custom colors — black on white
curl "https://linkshrink.dev/api/v1/qr/my-campaign.png?fg=000000&bg=ffffff" --output qr-bw.png

# Branded colors — SVG with custom hex
curl "https://linkshrink.dev/api/v1/qr/my-campaign.svg?fg=ff00aa&bg=0a0a0f" --output qr-brand.svg

# Use directly in an <img> tag (PNG or SVG):
# <img src="https://linkshrink.dev/api/v1/qr/my-campaign.svg" alt="QR Code">

curl -X DELETE \
  "https://linkshrink.dev/api/v1/my-campaign?delete_token=a1b2c3d4e5f6..."

# Success response:
# {
#   "status": "success",
#   "message": "Short URL deleted successfully",
#   "data": { "code": "my-campaign" }
# }

# Error (missing/wrong token):
# HTTP 401
# {
#   "error": "Unauthorized",
#   "message": "A delete_token is required to delete this link",
#   "hint": "Use the delete_token returned when the link was created"
# }

curl -X POST "https://linkshrink.dev/api/v1/verify/my-secret-link" \
  -H "Content-Type: application/json" \
  -d '{"password": "s3cret"}'

# Success — 200:
# { "status": "success", "data": { "code": "my-secret-link", "originalUrl": "https://example.com/secret" } }

# Wrong password — 401:
# { "error": "Invalid password", "message": "The provided password is incorrect." }

curl "https://linkshrink.dev/api/v1/unshorten?url=https%3A%2F%2Fbit.ly%2Fexample"

{
  "status": "success",
  "data": {
    "originalUrl": "https://bit.ly/example",
    "destinationUrl": "https://example.com/final-page",
    "redirectChain": [
      { "url": "https://bit.ly/example", "statusCode": 301 }
    ],
    "redirectCount": 1
  }
}

{
  "status": "success",
  "data": { ... }
}

{
  "error": "Failed to shorten URL",
  "message": "This alias is already taken"
}

# Shorten (with custom alias and 7-day TTL)
curl -X POST "https://linkshrink.dev/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","customAlias":"my-link","ttl_seconds":604800}'

# Get click stats
curl "https://linkshrink.dev/api/v1/stats/my-link"

# Download QR code (PNG, 512px)
curl "https://linkshrink.dev/api/v1/qr/my-link.png" --output qr.png

# Download SVG QR with custom brand colors
curl "https://linkshrink.dev/api/v1/qr/my-link.svg?fg=ff00aa&bg=ffffff" --output qr.svg

# Delete (requires deleteToken from creation response)
curl -X DELETE "https://linkshrink.dev/api/v1/my-link?delete_token=<token>"

# Bulk shorten 3 URLs
curl -X POST "https://linkshrink.dev/api/v1/shorten/bulk" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com/1","https://example.com/2","https://example.com/3"]}'

// Shorten a URL
const res = await fetch('https://linkshrink.dev/api/v1/shorten', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://example.com/very/long/path',
    customAlias: 'my-link',   // optional
    ttl_seconds: 86400         // optional — 1 day
  })
});
const { data } = await res.json();

console.log(data.shortUrl);    // https://linkshrink.dev/my-link
console.log(data.previewUrl);  // https://linkshrink.dev/preview/my-link
console.log(data.qrCode);      // QR code PNG URL
console.log(data.deleteToken); // Save this!

// Get click count
const stats = await fetch(`https://linkshrink.dev/api/v1/stats/${data.code}`);
const { data: s } = await stats.json();
console.log(s.clicks); // 42

// Delete the link
await fetch(
  `https://linkshrink.dev/api/v1/${data.code}?delete_token=${data.deleteToken}`,
  { method: 'DELETE' }
);

import requests

BASE = "https://linkshrink.dev/api/v1"

# Shorten a URL
response = requests.post(f"{BASE}/shorten", json={
    "url": "https://example.com/very/long/path",
    "customAlias": "my-link",  # optional
    "ttl_seconds": 86400        # optional — 1 day
})
data = response.json()["data"]

print(data["shortUrl"])    # https://linkshrink.dev/my-link
print(data["deleteToken"]) # save this

# Get click stats
stats = requests.get(f"{BASE}/stats/{data['code']}").json()["data"]
print(stats["clicks"])  # 42

# Download QR code (PNG)
qr = requests.get(f"{BASE}/qr/{data['code']}.png?size=256")
with open("qr.png", "wb") as f:
    f.write(qr.content)

# Download branded SVG QR code
svg = requests.get(f"{BASE}/qr/{data['code']}.svg?fg=ff00aa&bg=ffffff")
with open("qr.svg", "w") as f:
    f.write(svg.text)

# Delete the link
requests.delete(
    f"{BASE}/{data['code']}",
    params={"delete_token": data["deleteToken"]}
)

# Bulk shorten
bulk = requests.post(f"{BASE}/shorten/bulk", json={
    "urls": ["https://example.com/1", "https://example.com/2"],
    "ttl_seconds": 604800
}).json()
for item in bulk["data"]:
    print(item["data"]["shortUrl"] if item["success"] else item["error"])

{
  "mcpServers": {
    "linkshrink": {
      "command": "npx",
      "args": ["-y", "linkshrink-mcp"]
    }
  }
}