REST API v1

ShortLink API

Build link management, QR generation, and click analytics into your application with a simple REST API.

Introduction

The ShortLink API lets you create and manage short links, generate QR codes, and retrieve click analytics from your own application. All endpoints follow REST conventions and return JSON responses.

Base URL

https://api.shortlink.app/api/v1

Versioning

The current API version is v1. Breaking changes will be released under a new version path. The v1 path remains stable.

Request format

All POST and PATCH requests must include Content-Type: application/json and a JSON body. GET and DELETE requests do not require a body.

Authentication

Every request must include your API key in the Authorization header. Generate a key from your API Keys dashboard.

Header format

Authorization: Bearer YOUR_API_KEY

Example request

curl https://api.shortlink.app/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY"

Keep your API key secret. Do not expose it in client-side JavaScript or public repositories. Rotate it immediately if compromised.

Links API

Create, retrieve, update, and delete short links in your workspace.

POST/linksCreate a new short link

GET/linksList all links (paginated)

GET/links/:idGet a single link by ID

PATCH/links/:idUpdate link title or URL

DELETE/links/:idDelete a link

Create a short link

Shorten a URL and optionally set a title, UTM parameters, expiry, or password.

curl -X POST https://api.shortlink.app/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com/long-page",
    "title": "My Landing Page",
    "utm_source": "newsletter"
  }'

Request body fields

original_urlstringrequiredThe destination URL to shorten

slugstringoptionalCustom slug (auto-generated if omitted)

titlestringoptionalDisplay name for the link

utm_sourcestringoptionalUTM source parameter

utm_mediumstringoptionalUTM medium parameter

utm_campaignstringoptionalUTM campaign parameter

expires_atstringoptionalISO 8601 expiry date

passwordstringoptionalPassword-protect the link

List links

Returns a paginated list of links in your workspace.

curl "https://api.shortlink.app/api/v1/links?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

QR Codes API

Generate and manage QR codes linked to your short links.

POST/qrGenerate a new QR code

GET/qrList all QR codes

GET/qr/:idGet a single QR code

DELETE/qr/:idDelete a QR code

Generate a QR code

curl -X POST https://api.shortlink.app/api/v1/qr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "link_id": "LINK_ID",
    "name": "Product QR",
    "fg_color": "#1a1a1a",
    "bg_color": "#ffffff",
    "dot_style": "dots"
  }'

Style options

link_idstringLink ID to encode in the QR

namestringLabel for the QR code

fg_colorstringForeground color (hex, default #000000)

bg_colorstringBackground color (hex, default #ffffff)

dot_stylestringsquare | dots | rounded (default square)

corner_stylestringsquare | rounded (default square)

logo_urlstringURL of logo to embed in center

Analytics API

Retrieve click statistics for any link in your workspace. Data is available for the past 30 days on Free, 6 months on Pro, and 12 months on Business.

GET/analyticsWorkspace-level overview (total clicks, top links)

GET/analytics/links/:idPer-link breakdown (countries, devices, referrers)

Link analytics

Pass a period query parameter: 7d, 30d, or 90d.

curl "https://api.shortlink.app/api/v1/analytics/links/LINK_ID?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

API requests are rate-limited per API key on a rolling one-hour window. When you exceed the limit, the API returns a 429 Too Many Requests response.

Free100 requests / hour

Pro1,000 requests / hour

Business10,000 requests / hour

Rate limit headers are included in every response:

X-RateLimit-LimitMaximum requests allowed in the window

X-RateLimit-RemainingRequests remaining in the current window

X-RateLimit-ResetUnix timestamp when the window resets

Error Codes

All error responses follow a consistent format with an HTTP status code and a JSON body:

{
  "message": "A human-readable description of the error",
  "statusCode": 400
}

200OKRequest succeeded

201CreatedResource created successfully

400Bad RequestInvalid request body or parameters

401UnauthorizedMissing or invalid API key

403ForbiddenAction not allowed on your current plan

404Not FoundResource does not exist

409ConflictDuplicate slug or domain already registered

429Too Many RequestsRate limit exceeded

500Internal Server ErrorUnexpected server error

Ready to start building?

Generate your API key and start shortening links in minutes.