Skip to content
Public Endpoints

Public Endpoints

Availability: These endpoints need no API key and no plan. Browser scripts can call them only from shortn.link; elsewhere, call them from your server.

A few endpoints work without an API key. The shortener on shortn.link uses them to create links for visitors without an account, show those links’ stats, check URLs, draw QR codes and list plans. For everything else, see authentication.

Endpoints

MethodPathScope
POST/api/v1/linksNone, without a key
GET/api/v1/links/{code}/analyticsNone
GET/api/v1/validateNone
GET/api/v1/qrNone
GET/api/v1/plansNone

Create a link without a key

POST /api/v1/links without credentials creates an anonymous link that belongs to no account. Send url and title; custom share previews, tags and UTM templates need an API key (401 authentication_required).

curl -X POST https://app.shortn.link/api/v1/links \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/menu", "title": "Lunch menu"}'
{
  "public_id": "7d2e1f0a-3c4b-4a5d-8e6f-9a0b1c2d3e4f",
  "short_url": "https://shtnl.ink/abC12x9",
  "short_code": "abC12x9",
  "original_url": "https://example.com/menu",
  "title": "Lunch menu",
  "link_status": "active",
  "security_verdict": "clean",
  "expires_at": "2026-12-16T10:00:00Z"
}
  • An anonymous link expires and is deleted after 30 days.
  • Each IP address can create 3 anonymous links per UTC day. The fourth answers 429 anonymous_daily_limit, with a Retry-After header and details.reset_at.
  • Credentials that don’t validate are refused with 401 invalid_api_key; they never fall back to an anonymous link.

With an API key, the same endpoint creates a link in your account; see create a link.

Public preview of an anonymous link

GET /api/v1/links/{code}/analytics shows an anonymous link’s recent clicks. {code} is the short code or the full short URL.

curl https://app.shortn.link/api/v1/links/abC12x9/analytics
{
  "short_url": "https://shtnl.ink/abC12x9",
  "code": "abC12x9",
  "period_label": "Metrics and analytics from the last 3 days",
  "total_clicks": 12,
  "top_country": "Czechia",
  "top_country_code": "CZ",
  "top_source": "Direct",
  "top_referrer": "",
  "events_total": 12
}
  • It covers today and the two days before, in UTC, and returns totals and tops only, never individual visits.
  • top_source is the referrer with the most clicks, or Direct. top_country_code is XX when the country is unknown. events_total repeats total_clicks.
  • Links that belong to an account aren’t public: for them, as for an unknown code, the answer is 404 short_link_not_found. Use the analytics API for your own links.
  • 503 public_analytics_unavailable means analytics are temporarily unavailable.

Validate a URL

GET /api/v1/validate checks whether a URL can be a link’s destination and returns it as Shortn would store it.

FieldTypeRequiredNotes
urlstringyesThe URL to check.
curl "https://app.shortn.link/api/v1/validate?url=example.com/menu"
{ "valid": true, "normalized": "https://example.com/menu" }

An unusable URL still answers 200:

{ "valid": false, "code": "invalid_url", "error": "..." }

A missing url returns 400 url_required. This checks the URL’s form only; the safety checks run when you create the link.

Generate a QR code

GET /api/v1/qr returns a QR code image for a URL, cached for an hour.

FieldTypeRequiredNotes
urlstringyesThe URL the code opens, usually a short URL.
formatstringnopng (default), svg or jpg.
sizestringnopreview (default, about 400 px), preview-hd (800), preview-final (1,200), preview-xl (1,600) or download (4,000).
colorModestringnoflat (default) or gradient.
fgstringnoForeground color as hex, such as 1f2937. Default black.
bgstringnoBackground color as hex, or transparent (PNG and SVG). Default white.
gradientColorsstringno2 to 5 comma-separated hex colors, with colorMode=gradient. gradientStart, gradientMiddle and gradientEnd are the older form.
gradientDirstringnotlbr (default), trbl, ltr, rtl, ttb, btt or radial.
qrShapestringnoModule shape: rectangle (default), circle, liquid, chain, hstripe or vstripe.
finderShapestringnoCorner squares: match (default), square, rounded, circle or diagonal.
cornerStylestringnoBorder: none (default), square or rounded.
borderPatternstringnosimple (default), dashed, double, focus, chamfered, offset or blocks.
borderColorstringnoBorder color as hex. Defaults to the foreground color.
frameTemplatestringnoCall-to-action frame: none, scan or bubble.
frameTextstringnoThe frame’s text. Default SCAN ME.
frameTextColorstringnoThe frame text’s color as hex, with frameTextFollowsBackground=false. By default the text takes the background color.
brandingstringnodefault shows the Shortn mark; none removes it.

Without an account, the endpoint draws the options every plan has: flat colors, the simple border, rectangle or circle modules, matching corner squares, and the scan frame with its default text. Other options are for links designed in the dashboard; asking for them here returns 403 plan_limit_exceeded with feature: qr_customization. Download a styled code from the link’s QR Code tab instead; see QR codes.

curl -o menu-qr.png "https://app.shortn.link/api/v1/qr?url=https%3A%2F%2Fshtnl.ink%2FabC12x9&format=png&size=download"
StatusCodeMeaning
400url_requiredNo url.
400invalid_qr_destinationThe URL isn’t usable.
400invalid_qr_settingsAn option has an invalid value.
403plan_limit_exceededAn option needs a plan, as above.

List plans

GET /api/v1/plans returns the plan catalog, keyed by plan ID: free, starter, professional, agency, and the yearly starter_yearly, professional_yearly and agency_yearly.

curl https://app.shortn.link/api/v1/plans
{
  "plans": {
    "free": {
      "ID": "free",
      "Name": "Always Free",
      "Description": "Basic features to get started",
      "Price": 0,
      "Currency": "EUR",
      "Interval": "month",
      "Features": null,
      "PriceID": "",
      "MaxLinks": 25,
      "MaxClicks": 1000
    }
  }
}

This endpoint’s fields are capitalized, unlike the rest of the API. Price is in cents, Interval is month or year, MaxLinks is the active-link limit and MaxClicks the monthly click limit; -1 means unlimited. See plans for everything each plan includes.

Last updated on