REST API

Create and manage short links from your own apps. Create an API key in Dashboard → API keys, then send it as a Bearer token on every request.

Authorization: Bearer sk_your_key_here

Base URL: /api/v1 · All bodies are JSON · Rate limit: 120 requests per minute per key (HTTP 429 with Retry-After when exceeded).

Create a link

POST/api/v1/links

Field	Type	Description
`url`	string, required	Destination URL (http or https)
`slug`	string, optional	Custom alias, 3–50 chars: letters, numbers, `-`, `_`
`title`	string, optional	Private label for your dashboard

curl -X POST /api/v1/links \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/spring-collection","slug":"spring"}'

// 201 Created
{
  "link": {
    "id": 42, "slug": "spring", "short_url": "/spring",
    "url": "https://example.com/spring-collection", "title": "",
    "is_active": true, "clicks": 0, "created_at": 1767225600000, "updated_at": 1767225600000
  }
}

List links

GET/api/v1/links?page=1&limit=20

Returns your links, newest first. limit max 100.

Get a link

GET/api/v1/links/:slug

Update a link

PATCH/api/v1/links/:slug

Any of url, slug, title, is_active (boolean).

Delete a link

DELETE/api/v1/links/:slug

Link analytics

GET/api/v1/links/:slug/stats?days=30&tz=300

days 1–365. tz is your UTC offset in minutes for daily grouping (e.g. 300 for UTC+5). Returns the total, a per-day series and top countries, devices, browsers, operating systems and referrers.

{
  "stats": {
    "days": 30, "total": 128,
    "series": [{ "date": "2026-10-01", "clicks": 9 }, ...],
    "countries": [{ "label": "PK", "clicks": 71 }, ...],
    "devices":   [{ "label": "Mobile", "clicks": 102 }, ...],
    "browsers": [...], "os": [...], "referrers": [...]
  }
}

Errors

Errors return a non-2xx status with {"error": "message"}. Common codes: 400 invalid input, 401 bad or missing key, 404 not found, 409 alias taken, 429 rate limited.

JavaScript example

const res = await fetch('/api/v1/links', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' }),
});
const { link } = await res.json();
console.log(link.short_url);