Quickstart & REST API Reference

Integrate intelligent edge link shortening, real-time analytics, and conversion tracking with our high-performance REST API and TypeScript SDK.

5 min read•Official Edge Documentation

Overview & Architecture

The LShorter REST API provides programmatic access to all link management, edge routing, privacy masking, conversion attribution, and telemetry features of the LShorter platform.

All requests are routed to Cloudflare's global edge network (over 300+ data centers worldwide) to guarantee sub-15ms response times, 99.99% availability, and automatic TLS 1.3 encryption.

Developers can interact directly via standard HTTP requests or use the official typed Node.js / TypeScript SDK (lshorter-api).

Key Principles

Core architectural pillars ensuring high performance, isolation, and security.

01Standard REST & JSON

Predictable resource-oriented URLs, standard HTTP methods (GET, POST, PATCH, DELETE), and JSON-encoded request & response bodies.

02Bearer Token Authentication

Secure every request with the Authorization: Bearer <API_KEY> header. Manage keys and scopes directly from your developer dashboard.

03Tiered Rate Limits

Adaptive rate limits from 60 to 1,400 requests per minute based on your plan (Starter: 60, Pro: 200, Business: 600, Enterprise: 1,400), with real-time rate limit headers included in every HTTP response.

04Global Edge Execution

Redirection logic, geolocation resolution, and atomic click counters execute directly in V8 isolates at the Edge without origin latency.

SDK Integration

Implementation & SDK Examples

Ready-to-use TypeScript code snippets and configuration examples for your integrations.

1. Official SDK Installation

Install the official lshorter-api package using your favorite package manager:

bash

1
npm install lshorter-api

2. Client Initialization

Configure your LShorter client with your secret API key:

lib/lshorter.ts

typescript

12345678
import { LShorter } from "lshorter-api";
 
export const lshorter = new LShorter({
  apiKey: process.env.LSHORTER_API_KEY!,
  endpoint: "https://lsho.cc/api/v1", // Optional custom endpoint
  timeout: 5000, // 5s request timeout
  maxRetries: 3, // Auto-retry on 5xx or network hiccups
});

3. Creating Your First Short Link

Create a trackable short link with custom slug and tags:

create-link.ts

typescript

12345678910
import { lshorter } from "@/lib/lshorter";
 
const link = await lshorter.links.create({
  url: "https://my-store.com/summer-promo",
  slug: "summer-2026",
  tags: ["marketing", "summer-sale"],
});
 
console.log("Short URL generated:", link.shortUrl);
// Output: https://lsho.cc/summer-2026

4. Recording Conversion with Customer Avatar (avatarUrl & customerAvatar)

Record a sale with customer profile photo / avatar displayed in live dashboards:

track-purchase.ts

typescript

123456789101112131415
import { lshorter } from "@/lib/lshorter";
 
// Record monetary revenue and attribute it to the click with customer avatar
await lshorter.track.conversion({
  eventName: "purchase",
  amount: 49.00,
  currency: "USD",
  clickId: "clk_9921ab01", // Captured from the short link visit (?ref=clk_...)
  orderId: "ch_9921823ab",
  customer: {
    email: "alex@example.com",
    name: "Alex Johnson",
    avatarUrl: "https://lh3.googleusercontent.com/a/ACg8oc...", // Profile photo from Google OAuth or Gravatar
  },
});

5. Querying Real-Time Revenue & Clicks Telemetry

Fetch live click counts, tracked revenue amount, and average earnings per click (EPC):

get-analytics.ts

typescript

1234567
import { lshorter } from "@/lib/lshorter";
 
const stats = await lshorter.analytics.getRevenue("summer-2026", { period: "30d" });
 
console.log("Total Clicks:", stats.totalClicks);
console.log("Tracked Revenue:", stats.trackedRevenue, "USD");
console.log("Earnings Per Click (EPC):", stats.epc, "USD/click");

REST API Specification

API Endpoints & Reference

Direct HTTP request methods, parameters schema, authentication, and responses.

POST

Create Short Link

Bearer <API_KEY>60 to 1,400 req/min (by plan)

https://lsho.cc/api/v1/links

Creates a new shortened URL with optional custom slug, tags, expiration timestamp, maximum click limits, PIN protection, branded URL masking, and geographic routing rules.

Headers

Parameter	Type	Required	Description	Example
Authorization	string	Required	Bearer token containing your secret API key.	`Bearer lsho_live_89f023ab912`
Content-Type	string	Required	Must be set to application/json.	`application/json`

Request Body Parameters

Parameter	Type	Required	Description	Example
url	string (url)	Required	The destination URL that visitors will be redirected to.	`https://my-store.com/summer-sale`
slug	string	Optional	Custom alias for the link. If omitted, a high-entropy 7-character string is generated automatically.	`summer-2026`
tags	string[]	Optional	Array of categorization tags for filtering analytics.	`["marketing", "summer-promo"]`
maxClicks	number	Optional	Maximum authorized clicks before the link automatically deactivates.	`500`
expiresAt	string (ISO 8601)	Optional	UTC expiration timestamp after which the link becomes inactive.	`2026-10-31T23:59:59Z`
expiredRedirectUrl	string (url)	Optional	Alternative fallback URL to redirect visitors to after the link expires.	`https://my-store.com/sale-ended`
pinCode	string (4 digits)	Optional	4-digit security PIN required to access the destination URL.	`8492`
maskUrl	boolean	Optional	When true, masks destination URL by serving content inside a branded iframe.Default: `false`	`false`
metaTitle	string	Optional	Custom Open Graph / social media title.	`Exclusive Summer Offer`
ogDescription	string	Optional	Custom Open Graph description for social preview cards.	`Get 30% off our 2026 collection today.`
ogImage	string (url)	Optional	Banner image URL (1200x630px) for social media previews.	`https://my-store.com/og-banner.jpg`

Request Examples

bash

12345678910
curl -X POST "https://lsho.cc/api/v1/links" \
  -H "Authorization: Bearer $LSHORTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-store.com/summer-sale",
    "slug": "summer-2026",
    "tags": ["marketing", "summer-promo"],
    "maxClicks": 500,
    "expiresAt": "2026-10-31T23:59:59Z"
  }'

Response Payload

201 CreatedShort link created successfully.

response-201.json

json

123456789101112131415161718
{
  "id": "link_89f023ab912",
  "slug": "summer-2026",
  "shortUrl": "https://lsho.cc/summer-2026",
  "targetUrl": "https://my-store.com/summer-sale",
  "domain": "lsho.cc",
  "clicksCount": 0,
  "uniqueClicks": 0,
  "maxClicks": 500,
  "remainingClicks": 500,
  "expiresAt": "2026-10-31T23:59:59.000Z",
  "isProtected": false,
  "maskUrl": false,
  "tags": ["marketing", "summer-promo"],
  "status": "active",
  "createdAt": "2026-09-17T12:00:00.000Z",
  "updatedAt": "2026-09-17T12:00:00.000Z"
}

Possible Error Responses

HTTP Status	Error Code	Description
400	`INVALID_URL`	The destination URL provided is invalid or malformed.
401	`UNAUTHORIZED`	Missing or invalid Bearer API key.
409	`SLUG_ALREADY_EXISTS`	The requested custom slug is already claimed by another link.
422	`INVALID_EXPIRATION`	expiresAt must be a valid future ISO 8601 timestamp.
429	`RATE_LIMIT_EXCEEDED`	You have exceeded your account's rate limit for your current plan.

GET

List Short Links

Bearer <API_KEY>60 to 1,400 req/min (by plan)

https://lsho.cc/api/v1/links

Retrieves a paginated list of all short links created under your organization, with optional search query, tag filters, and sort orders.

Query Parameters

Parameter	Type	Required	Description	Example
page	number	Optional	Page number to retrieve.Default: `1`	`1`
limit	number	Optional	Number of links per page (max 100).Default: `20`	`20`
tag	string	Optional	Filter links by specific tag name.	`marketing`
search	string	Optional	Search query matching against slug or target URL.	`summer`
sortBy	string (createdAt \| clicksCount \| remainingClicks)	Optional	Sorting criteria.Default: `createdAt`	`clicksCount`
order	string (asc \| desc)	Optional	Sort direction.Default: `desc`	`desc`

Request Examples

bash

12
curl -X GET "https://lsho.cc/api/v1/links?page=1&limit=20&tag=marketing" \
  -H "Authorization: Bearer $LSHORTER_API_KEY"

Response Payload

200 OKList of short links returned with pagination metadata.

response-200.json

json

1234567891011121314151617181920212223
{
  "data": [
    {
      "id": "link_89f023ab912",
      "slug": "summer-2026",
      "shortUrl": "https://lsho.cc/summer-2026",
      "targetUrl": "https://my-store.com/summer-sale",
      "clicksCount": 1420,
      "uniqueClicks": 1180,
      "tags": ["marketing", "summer-promo"],
      "status": "active",
      "createdAt": "2026-09-17T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Recommended Best Practices

Expert tips to maximize performance, resilience, and link security.

Recommendation 01

Keep your API key private: Store it in environment variables (LSHORTER_API_KEY) and never check it into public version control.

Recommendation 02

Use HTTP Keep-Alive connection pooling across requests to minimize TLS handshake latency.

Recommendation 03

Inspect rate limit headers (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset) to proactively manage traffic spikes.

Recommendation 04

Implement idempotent request handling when retrying POST endpoints.

Next guideDynamic Routing & Edge Geolocation

Related Guides & APIs

Overview & Architecture

The LShorter REST API provides programmatic access to all link management, edge routing, privacy masking, conversion attribution, and telemetry features of the LShorter platform.

All requests are routed to Cloudflare's global edge network (over 300+ data centers worldwide) to guarantee sub-15ms response times, 99.99% availability, and automatic TLS 1.3 encryption.

Developers can interact directly via standard HTTP requests or use the official typed Node.js / TypeScript SDK (lshorter-api).

12345678

import { LShorter } from "lshorter-api"; export const lshorter = new LShorter({ apiKey: process.env.LSHORTER_API_KEY!, endpoint: "https://lsho.cc/api/v1", // Optional custom endpoint timeout: 5000, // 5s request timeout maxRetries: 3, // Auto-retry on 5xx or network hiccups });

12345678910

import { lshorter } from "@/lib/lshorter"; const link = await lshorter.links.create({ url: "https://my-store.com/summer-promo", slug: "summer-2026", tags: ["marketing", "summer-sale"], }); console.log("Short URL generated:", link.shortUrl); // Output: https://lsho.cc/summer-2026

123456789101112131415

import { lshorter } from "@/lib/lshorter"; // Record monetary revenue and attribute it to the click with customer avatar await lshorter.track.conversion({ eventName: "purchase", amount: 49.00, currency: "USD", clickId: "clk_9921ab01", // Captured from the short link visit (?ref=clk_...) orderId: "ch_9921823ab", customer: { email: "alex@example.com", name: "Alex Johnson", avatarUrl: "https://lh3.googleusercontent.com/a/ACg8oc...", // Profile photo from Google OAuth or Gravatar }, });

1234567

import { lshorter } from "@/lib/lshorter"; const stats = await lshorter.analytics.getRevenue("summer-2026", { period: "30d" }); console.log("Total Clicks:", stats.totalClicks); console.log("Tracked Revenue:", stats.trackedRevenue, "USD"); console.log("Earnings Per Click (EPC):", stats.epc, "USD/click");

Parameter

Type

Required

Description

Example

Authorization

string

Required

Bearer token containing your secret API key.

Bearer lsho_live_89f023ab912

Content-Type

string

Required

Must be set to application/json.

application/json

Parameter

Type

Required

Description

Example

url

string (url)

Required

The destination URL that visitors will be redirected to.

https://my-store.com/summer-sale

slug

string

Optional

Custom alias for the link. If omitted, a high-entropy 7-character string is generated automatically.

summer-2026